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APPEAL BRIEF 



Honorable Commissioner: 



This is an Appeal Brief filed pursuant to 37 CFR § 41.37 in response to the Final Office 
Action of June 30, 2005 ('Final Office Action'), and pursuant to the Notice of Appeal 
filed September 30, 2005. 



REAL PARTY IN INTEREST 



The real party in interest is the patent assignee, International Business Machines 
Corporation ("IBM"), a New York corporation having a place of business at Armonk, 
New York 10504. 
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RELATED APPEALS AND INTERFERENCES 

There are no related appeals or interferences. 

STATUS OF CLAIMS 

Claims 1-36 are pending in the case. All pending claims are on appeal. 

STATUS OF AMENDMENTS 

No amendments were submitted after final rejection. The claims as currently presented 
are included in the Appendix of Claims that accompanies this Appeal Brief. 

SUMMARY OF CLAIMED SUBJECT MATTER 

Applicants provide the following concise summary of the claimed subject matter 
according to 37 CFR § 41.37(c)(l)(vii), including references to specification by page and 
line number and to the drawing(s) if any, by reference characters. 

Methods, systems, and computer program products are provided for remote direction of 
streaming digital content from a multiplicity of sources of digital information to a 
multiplicity of client devices the method implemented upon a network of digital 
computers, at least one of the digital computers comprising a content server upon which 
the steps of the method are implemented in computer memory and at least one computer 
processor (described for example at reference numbers 100, 102, 106, and 108 in Figure 
1 and lines 5-9 on page 13). Embodiments of methods typically include receiving digital 
content from the sources, the digital content having a multiplicity of digital formats 
(described for example at reference numbers 106 and 221 in Figure 2 and lines 1 1-17 on 
page 13); receiving, from a remote director, and storing in computer memory, remote 
director instructions, the remote director instructions including instructions for selections 
of digital content for inclusion in an output stream (described for example at references 
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numbers 104, 202, and 204 in Figure 2 and lines 19-22 on page 13); transcoding the 
digital content from sources into digital content having streaming format (described for 
example at references 220 and 223 and lines 22-23 on page 13); including in an output 
stream, in dependence upon the remote director's instructions, digital content having 
streaming format (described for example at reference 225 in Figure 2 and lines 25-27 on 
page 13); and communicating to at least one of the client devices the output stream 
(described for example at references 102 and 225 in Figure 2 and line 27 on page 13 
through line 2 on page 14). In typical embodiments, the client devices comprise client 
device attributes, said transcoding further comprising transcoding in dependence upon the 
client device attributes (described for example at lines 4-7 on page 14 and lines 1 1-17 on 
page 14). In typical embodiments, client device attributes include device type, screen 
size, frame rate, and audio status (described for example at lines 7-9 on page 14). 

In typical embodiments, a remote director comprises a personal computer coupled 
through a network to a content server, and embodiments of inventive methods typically 
include sending from the remote director to the content server remote director 
instructions (described for example at references 100, 104, and 204 in Figure 2 and line 
19 on page 14 through line 3 on page 15). In typical embodiments, a hyperlinked URL 
invoked through a hot spot on a video screen of a remote director in turn invokes on a 
content server a servlet (described for example at lines 7-17 on page 1 1 and lines 5-9 on 
page 15). A servlet in typical embodiments is an object, an aggregate of data elements 
and member methods, containing member methods for administration of digital content 
from sources, transcoding, selecting, and communicating the selected, transcoded digital 
content to client devices (described for example at lines 13-18 on page 9 and lines 11-18 
on page 10). 

In typical embodiments, member methods in a servlet function to receive hyperlinks to 
remote director instructions in the form of URLs wherein the URLs identify specific 
member methods, either in the servlet or in other related class objects (described for 
example at lines 19-22 on page 1 1 and lines 5-9 on page 15). The remote director 
instructions in such embodiments include both a URL and a member method or computer 
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program name. The specific member methods so identified comprise computer programs 
each of which is fashioned to carry out a particular task involved in transcoding, 
selecting, and communicating to client devices digital content from sources (described for 
example at line 19 on page 14 through line 3 on page 15). Carrying out a remote director 
instruction includes executing the computer program or member method identified by the 
URL of the remote director instruction (described for example at line 19 on page 14 
through line 3 on page 15 and line 18 on page 16 through line 18 on page 17). 

In some embodiments, the member methods identified by URLs of remote director 
instructions are executed as separate computational processes, so-called heavyweight 
processes each execution of which involved a full context switch at the operating system 
level. In many embodiments of the present invention, however, the member methods 
identified by URLs of remote director instructions are executed as lightweight threads of 
execution, sharing memory segments with other threads and not requiring full context 
switches for execution. Many embodiments implement servlets in Java at least partly 
because Java as a computer language has particular support for threaded program 
execution in the form of Java's thread-level URL dispatch routines. In typical 
embodiments of the present invention, the member methods identified by URLs of 
remote director instructions are implemented as Java thread-level URL dispatch routines 
(described for example at lines 1-2 on page 15). In typical embodiments, a remote 
director instruction comprises an instruction to select for transcoding and streaming 
digital content from a specific source (described for example at lines 2-3 on page 15). 

Embodiments of inventive methods typically include also registering a user for a service, 
the service identified by a service identification code, the service comprising at least one 
digital content stream (described for example at references 208, 226, 234, 236, and 237 in 
Figure 2 and lines 3-14 on page 18); logging in the user for the service, logging in the 
user further comprising assigning values to user login attributes, the user login attributes 
comprising user identification, device type, network address, and a tier (described for 
example at references 206, 218, 226, 228, 230, and 232 in Figure 2, references 232, 228, 
242, 244, 246, 234, 236, 238, and 240 in Figure 2a, and line 16 on page 18 through line 
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16 on page 19); and assigning a tier value in dependence upon the device type and the 
service identification code (described for example at lines 18-25 on page 19); wherein the 
selections are dependent upon the tier (described for example at lines 19-20 on page 19); 
wherein transcoding further comprises transcoding in dependence upon the tier 
(described for example at references 102, 103, 218, 220, 224, 225, 410, and 414 in Figure 
3 and lines 1-10 on page 23); and wherein communicating to at least one of the client 
devices the output stream further comprises communicating the output stream to the 
network address (described for example at lines 15-24 on page 20). In typical 
embodiments, registering a user includes creating a service registration record comprising 
service registration attributes comprising user id, service id and service subscription level 
and assigning a tier value further comprises assigning a tier value in dependence upon the 
service subscription level (described for example at reference numbers 208, 226, 234, 
236, and 237 in Figure 2 and lines 18-25 on page 19). 

Typical embodiments include registering a user for an event, the event in typical 
embodiments identified by an event identification code, the event comprising at least one 
digital content stream, at least one source, a start date and a start time (described for 
example at references 210, 226, 238, 240, 264, and 266 in Figure 2 and reference 238 in 
Figure 2e and lines 10-17 on page 21); logging in the user for the event, logging in the 
user further comprising assigning values to user login attributes, the user login attributes 
comprising user identification, device type, network address, and a tier (described for 
example at references 206, 226, 228, 230, and 232 of Figure 2 and lines 1-4 on page 22); 
and assigning a tier value in dependence upon the device type and the event identification 
code (described for example at reference 240 in Figure 2 and lines 6-9 on page 22); 
wherein the selections are dependent upon the tier (described for example at lines 7-14 on 
page 24); wherein transcoding further comprises transcoding in dependence upon the tier 
(described for example at lines 7-14 on page 24); and wherein communicating to at least 
one of the client devices the output stream further comprises communicating the output 
stream to the network address (described for example at lines 7-14 on page 24). In 
typical embodiments, registering a user includes creating an event registration record 
comprising event registration attributes comprising user id, event id, event subscription 
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level, start date, and start time and assigning a tier value further comprises assigning a 
tier value in dependence upon the event subscription level (described for example at lines 
6-9 on page 22). 

All such references to the specification identify descriptions and discussions that are part 
of the detailed descriptions of exemplary embodiments of the present invention in the 
present application. Such descriptions and discussions are not limitations of the claims in 
the present application. The only limitations of the claims are set forth in the claims 
themselves. 

GROUNDS OF REJECTION 

Claims 1-36 in the present application are rejected in the Final Office Action dated June 
30, 2005 for obviousness-type double patenting over claims 1-22 of co-pending 
Application No. 09/882174, over claims 10-15 of co-pending Application No. 09/881919, 
over claims 1-20 of co-pending Application No. 09/881917, and over claims 1-12 of co- 
pending Application No. 09/882173. As explained in detail below, Applicants 
respectfully traverse the obviousness-type double patenting rejections of the present 
claims. 

Independent claims 1, 13, and 25 stand rejected under 35 U.S.C § 103(a) as unpatentable 
over a first reference entitled Application Server Solution Guide, Enterprise Edition: 
Getting Started , Nusbaum, et al., May 2000, pages 1-45, 416-434 (hereafter 'Nusbaum'), 
and in view of a second reference entitled Java Media Framework API Guide, JMP 2.0 
FCS, November 19, 1999, Sun Microsystems, pages 1-66, 109-135, 173-178 (hereafter 
'Sun'). As explained in detail below, Applicants respectfully traverse the rejections of the 
present claims under 35 USC § 103(a). 
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ARGUMENT 

REJECTIONS FOR CLAIMS 1-36 BASED ON OBVIOUSNESS-TYPE 
DOUBLE PATENTING ARE IMPROPER 

All claims in the present application are rejected in the Final Office Action for 
obviousness-type double patenting over claims 1-22 of co-pending Application No. 
09/882174, overclaims 10-15 of co-pending Application No. 09/881919, overclaims 1- 
20 of co-pending Application No. 09/881917, and over claims 1-12 of co-pending 
Application No. 09/882173. 

The law governing double patenting is that the analysis employed in an obviousness-type 
double patenting determination parallels the guidelines for a 35 U.S.C. § 103(a) rejection. 
The factual inquiries set forth in Graham v. John Deere Co., 383 U.S. 1, 148 USPQ 459 
(1966) are applied for establishing a background for determining obviousness under 35 
U.S.C. § 103 and are employed when making an obviousness-type double patenting 
rejection. Manual of Patent Examining Procedure § 804 IIB1. The Graham factual 
inquiries require the Examiner to: 

• determine the scope and content of the art as described in each co-pending 
application; 

• determine the differences between the scope and content of the art as described in 
each co-pending application and the claims at issue; 

• determine the level of ordinary skill in the pertinent art; and 

• evaluate any objective indicia of nonobviousness. 
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Co-pending Application No. 09/882 1 74 

The Final Office Action rejects claims 1-36 for obviousness-type double patenting as 
being unpatentable over 1-22 of co-pending Application No. 09/882174. The Final 
Office Action at page 8 states: 

. . . they are not patentably distinct from each other because the limitations of the 
independent claims 1 5 13, 26 are similar to claim 1 of co-pending Application No. 
09/882174. The limitations, "remote direction of streaming digital content from a 
content server to a client devices using remote director" is equivalent to the use of 
content information, transcoding gateway for providing director instructions to 
stream digital content, and the use of email containing digital content. The 
limitations of dependent claims 2-12, 14-23, 26-36, are similar to claims 2-22 of 
co-pending Application No. 09/882174. 

As described above, the Final Office Action must apply the Graham factors to establish 
the required background for a double patenting rejection. Although the Final Office 
Action does not even mention the Graham factors, the Final Office Action at pages 8 and 
9 states: 

The co-pending application handles transcoding information using the 
network device. The current application also handles transcoding 
information using the network device. The claimed subject matter of the 
co-pending application does not mention about the transcoding being done 
using remote director instruction. However, the concept of using remote 
director instructions is well known in the art. For example, Nusbaum 
discloses usage of remote director instructions (e.g., servlet aliases, servlet 
URLs, sections 1.1 and 1.2, pages 1 and 2). The remote director 
instructions would help provide instructions to perform the transcoding 
from a remote device. 
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Applicants take the assertion in the Final Office Action that co-pending Application No. 
09/882174 "handles transcoding information using the network device" as a 
determination under Graham of the scope and content of the art as described in co- 
pending application No. 09/8821 74. In response, Applicants note that the Final Office 
Action mischaracterizes co-pending application No. 09/882174 by asserting that the co- 
pending application transcodes information using a network device. Co-pending 
application No. 09/882174 claims a transcoding gateway for "transcoding the digital 
object into a digital file having a digital format and a file name. . . ." The scope and 
content of the art as described in co-pending application No. 09/882174 therefore 
includes a transcoding gateway that transcodes a digital object into a digital file having a 
digital format and a file name. The scope and content of the art as described in co- 
pending application No. 09/882174 does not include any network device that transcodes 
information as asserted in the Final Office Action. Because the Final Office Action does 
not properly determine the scope and content of the art as described in co-pending 
application No. 09/882174, the Final Office Action does not establish the necessary 
background for determining obviousness. Without establishing the necessary background 
for determining obviousness, the Final Office Action cannot support an obviousness-type 
double patenting rejection, and the rejections of claims 1-36 should be withdrawn. 

Applicants take the assertion in the Final Office Action that "[t]he current application 
also handles transcoding information using the network device" and that "[t]he claimed 
subject matter of the co-pending application does not mention about the transcoding 
being done using remote director instruction" as a determination under Graham of the 
differences between the scope and content of the art as described in co-pending 
application No. 09/882174 and the claims at issue. In response, Applicants note that the 
Final Office Action mischaracterizes the present application by asserting that the present 
application transcodes information using a network device. The present application 
claims a content server for "transcoding, in dependence upon the remote director's 
instructions, the digital content from sources into digital content having streaming 
format. . . ." The scope and content of the art as described in the present application 
therefore includes a content server that transcodes, in dependence upon the remote 
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director's instructions, the digital content from sources into digital content having 
streaming format, not any network device that transcodes information as asserted in the 
Final Office Action. Because the Final Office Action does not properly determine the 
scope and content of the art as described in the present application, the Final Office 
Action cannot determine the differences between the scope and content of the art as 
described in co-pending application No. 09/882174 and the claims at issue. The Final 
Office Action therefore does not establish the necessary background for determining 
obviousness. Without establishing the necessary background for determining 
obviousness, the Final Office Action cannot support an obviousness-type double 
patenting rejection, and the rejections of claims 1-36 should be withdrawn. 

Applicants further assume that the Final Office Action at pages 8 and 9 attempts to 
determine under Graham the level of ordinary skill in the pertinent art by stating: 

However, the concept of using remote director instructions is well known 
in the art. For example, Nusbaum discloses usage of remote director 
instructions (e.g., servlet aliases, servlet URLs, sections 1.1 and 1.2, pages 
1 and 2). The remote director instructions would help provide instructions 
to perform the transcoding from a remote device. 

The Final Office Action cites sections 1.1 and 1.2 of Nusbaum in an attempt to determine 
that remote director instructions are within the level of ordinary skill in the pertinent art. 
In response, Applicants note that Nusbaum is not 'pertinent art 5 available for determining 
under Graham the level of ordinary skill in the pertinent art because Nusbaum is not in 
the field of the Applicants' endeavor or reasonably pertinent to the particular problem 
with which the Applicants were concerned. In fact, Nusbaum cannot be a reference 
against the claims of the present application because Nusbaum does actually represent 
nonanalogous art within the meaning of In Re Horn, Clay, and Oeitker. In re Horn, 203 
USPQ 969 (CCPA 1979), In re Clay, 966 F.2d 656, 23 USPQ2d 1058 (Fed. Cir. 1992), 
In re Oeticker, 977 F.2d 1443, 24 USPQ2d 1443 (Fed. Cir. 1992). The field of the 
inventors' effort in this case is streaming digital content under remote direction. The 
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present application claims, among other things, receiving digital content from the 
sources, the digital content having a multiplicity of digital formats, receiving, from a 
remote director, and storing in computer memory, remote director instructions, the 
remote director instructions including instructions for selections of digital content for 
inclusion in an output stream, and transcoding, in dependence upon the remote director's 
instructions, the digital content from sources into digital content having streaming format. 
The field of Nusbaum is dynamic web pages for the World Wide Web - which has 
nothing to do with the technical field of the present application and is not reasonably 
pertinent to the particular problem with which the Applicants were concerned. Because 
Nusbaum is neither within the field of the inventor's endeavor in this case nor reasonably 
pertinent to the particular problem with which the Applicants were concerned, Nusbaum 
is not pertinent art available for determining the level of ordinary skill in the pertinent art 
under Graham, The Final Office Action therefore cannot establish the necessary 
background for determining obviousness and cannot support an obviousness-type double 
patenting rejection. The rejections of claims 1-36 should be withdrawn. 

Even if Nusbaum was pertinent art, which Nusbaum is not, sections 1.1 and 1.2 of 
Nusbaum do not disclose usage of remote director instructions as claimed in the present 
application. What section 1.1 of Nusbaum actually discloses is a general use of the term 
'application' in the context of IBM's WebSphere® product that provides integration and 
application infrastructure. What section 1.2 of Nusbaum actually discloses is a general 
description of Java servlets. A Java servlet is a software module that extends 
request/response oriented servers, such as Java-enabled web servers. Sections 1.1 and 1.2 
of Nusbaum have nothing to do with remote director instructions. Nusbaum' s general 
use of an application in the context of WebSphere® and Nusbaum' s general description of 
Java servlets does not disclose remote director instructions as claimed in the present 
application. Because sections 1.1 and 1.2 of Nusbaum do not disclose remote director 
instructions as claimed in the present application, the Final Office Action does not 
properly establish the level of ordinary skill in the pertinent art. The Final Office Action 
therefore does not establish the necessary background for determining obviousness and 
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cannot support an obviousness-type double patenting rejection. The rejections of claims 
1 -36 should be withdrawn. 

Co-Pending Application No. 09/881919 

The Final Office Action rejects claims 1-36 for obviousness-type double patenting as 
being unpatentable over claims 10-15 of co-pending Application No. 09/881919. The 
Final Office Action at page 9 states: 

. . . they are not patentably distinct from each other because the limitations of the 
independent claims 1, 13, 26 are similar to claim 10 of co-pending Application 
No. 09/881919. The limitations, "remote direction of streaming digital content 
from a content server to a client devices using remote director" is equivalent to 
the use of a content server through which digital content is transcoded into 
streams of multimedia data, the streams communicated via network to client 
devices, use of the digital content for streaming, use of remote director 
instructions comprising hyperlinked URSs invoked through a network-capable 
device. The limitations of dependent claims 2-12, 14-23, 26-36, are similar to 
claims 11-15 of co-pending Application No. 09/881919. 

As described above, the Final Office Action must apply the Graham factors to establish 
the required background for a double patenting rejection. Although the Final Office 
Action does not even mention the Graham factors, the Final Office Action does recite the 
same assertions made regarding co-pending Application No. 09/882174 above by stating: 

The co-pending application handles transcoding information using the 
network device. The current application also handles transcoding 
information using the network device. The claimed subject matter of the 
co-pending application does not mention about the transcoding being done 
using remote director instruction. However, the concept of using remote 
director instructions is well known in the art. For example, Nusbaum 
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discloses usage of remote director instructions (e.g., servlet aliases, servlet 
URLs, sections LI and 1.2, pages 1 and 2). The remote director 
instructions would help provide instructions to perform the transcoding 
from a remote device. 

Applicants take such assertions as an attempt to apply the Graham factors regarding this 
co-pending Application No. 09/881919. In response, Applicants note that the Final 
Office Action does not establish the necessary background for determining obviousness 
for the reasons discussed above with regard to co-pending Application No. 09/882174. 
The Final Office Action therefore cannot support an obviousness-type double patenting 
rejection, and the rejections of claims 1-36 should be withdrawn. 

Co-Pending Application No. 09/881917 

The Final Office Action rejects claims 1-36 for obviousness-type double patenting as 
being unpatentable over claims 1 -20 of co-pending Application No. 09/88 1 91 7. The 
Final Office Action at page 10 states: 

. . . they are not patentably distinct from each other because the limitations of the 
independent claims 1, 13, 26 are similar to claim 1 of co-pending Application No. 
09/881917. The limitations, "remote direction of streaming digital content from a 
content server to a client devices using remote director" is equivalent to the use of 
streaming digital content from a multiplicity of sources of digital information to a 
multiplicity of client devices, use of network of digital computers comprising a 
content server. The limitations of dependent claims 2-12, 14-23, 26-36, are 
similar to claims 2-20 of co-pending Application No. 09/881917. 

As described above, the Final Office Action must apply the Graham factors to establish 
the required background for a double patenting rejection. Although the Final Office 
Action does not even mention the Graham factors, the Final Office Action does recite the 
same assertions made regarding co-pending Application No. 09/882174 above by stating: 

13 



AUS920010502US1 
APPEAL BRIEF 



The co-pending application handles transcoding information using the 
network device. The current application also handles transcoding 
information using the network device. The claimed subject matter of the 
co-pending application does not mention about the transcoding being done 
using remote director instruction. However, the concept of using remote 
director instructions is well known in the art. For example, Nusbaum 
discloses usage of remote director instructions (e.g., servlet aliases, servlet 
URLs, sections 1.1 and 1.2, pages 1 and 2). The remote director 
instructions would help provide instructions to perform the transcoding 
from a remote device. 

Applicants take such assertions as an attempt to apply the Graham factors regarding this 
co-pending Application No. 09/881917. In response, Applicants note that the Final 
Office Action does not establish the necessary background for determining obviousness 
for the reasons discussed above with regard to co-pending Application No. 09/882174. 
The Final Office Action therefore cannot support an obviousness-type double patenting 
rejection, and the rejections of claims 1-36 should be withdrawn. 

Co-Pending Application No. 09/882173 

The Final Office Action rejects claims 1-36 for obviousness-type double patenting as 
being unpatentable over claims 1-12 of co-pending Application No. 09/882173. The 
Final Office Action at page 1 1 states: 

. . . they are not patentably distinct from each other because the limitations of the 
independent claims 1, 13, 26 are similar to claim 1 of co-pending Application No. 
09/882173. The limitations, "remote direction of streaming digital content from a 
content server to a client devices using remote director" is equivalent to the use of 
remote direction of streaming digital content from a multiplicity of sources of 
digital information to a multiplicity of client devices upon a network of digital 
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computer comprising a content server receiving digital content from the sources 
and the digital content having a multiplicity of digital formats. The limitations of 
dependent claims 2-12, 14-23, 26-36, are similar to claims 2-12 of co-pending 
Application No. 09/882173. 

As described above, the Final Office Action must apply the Graham factors to establish 
the required background for a double patenting rejection. Although the Final Office 
Action does not even mention the Graham factors, the Final Office Action does recite the 
same assertions made regarding co-pending Application No. 09/882174 above by stating: 

The co-pending application handles transcoding information using the 
network device. The current application also handles transcoding 
information using the network device. The claimed subject matter of the 
co-pending application does not mention about the transcoding being done 
using remote director instruction. However, the concept of using remote 
director instructions is well known in the art. For example, Nusbaum 
discloses usage of remote director instructions (e.g., servlet aliases, servlet 
URLs, sections 1.1 and 1.2, pages 1 and 2). The remote director 
instructions would help provide instructions to perform the transcoding 
from a remote device. 

Applicants take such assertions as an attempt to apply the Graham factors regarding this 
co-pending Application No. 09/882173. In response, Applicants note that the Final 
Office Action does not establish the necessary background for determining obviousness 
for the reasons discussed above with regard to co-pending Application No. 09/882174. 
The Final Office Action therefore cannot support an obviousness-type double patenting 
rejection, and the rejections of claims 1-36 should be withdrawn. 
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Conclusion 

The Final Office Action does not establish the necessary background for determining 
obviousness required by an obviousness-type double patenting rejection of claims 1-36 in 
the present application over claims 1-22 of co-pending Application No. 09/882174, over 
claims 10-15 of co-pending Application No. 09/881919, over claims 1-20 of co-pending 
Application No. 09/881917, and over claims 1-12 of co-pending Application No. 
09/8821 73. Based on the reasoning provided in the Final Office Action, no person of 
ordinary skill in the art would conclude that claims 1-36 in the present case are obvious in 
view of claims 1-22 of co-pending Application No. 09/882174, over claims 10-15 of co- 
pending Application No. 09/881919, over claims 1-20 of co-pending Application No. 
09/881917, and over claims 1-12 of co-pending Application No. 09/882173. Applicants 
therefore respectfully traverse the rejections of claims 1-36 and request reconsideration of 
claims 1-36 in light of the present remarks. 

REJECTIONS FOR CLAIMS 1-36 BASED ON OBVIOUSNESS 
UNDER 35 U.S.C § 103(a) ARE IMPROPER 

Claims 1-36 are in the case. Independent claims 1,13, and 25 stand rejected for 
obviousness under 35 U.S.C § 103(a) as unpatentable over a first reference entitled 
A pplication Server Solution Guide, Enterprise Edition: Getting Started . Nusbaum, et al., 
May 2000, pages 1-45, 416-434 (hereafter 'Nusbaum'), and in view of a second reference 
entitled Java Media Framework API Guide , JMP 2.0 FCS, November 19, 1999, Sun 
Microsystems, pages 1-66, 109-135, 173-178 (hereafter 'Sun'). To establish a prima 
facie case of obviousness, three basic criteria must be met. Manual of Patent Examining 
Procedure §2142. The first element of a prima facie case of obviousness under 35 
U.S.C. § 103 is that Nusbaum and Sun must teach or suggest all of Applicants' claim 
limitations. In re Royka, 490 F.2d 981, 985, 180 USPQ 580, 583 (CCPA 1974). The 
second element of a prima facie case of obviousness under 35 U.S.C. § 103 is that there 
must be a suggestion or motivation to combine Nusbaum and Sun. In re Vaeck, 947 F.2d 
488, 493, 20 USPQ2d 1438, 1442 (Fed. Cir. 1991). The third element of a prima facie 
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case of obviousness under 35 U.S.C. § 103 is that there must be a reasonable expectation 
of success in the proposed combination of Nusbaum and Sun. In re Merck & Co., Inc., 
800 F.2d 1091, 1097, 231 USPQ 375, 379 (Fed. Cir. 1986). As demonstrated below, the 
combination of Nusbaum and Sun does not establish a prima facie case of obviousness. 
The rejection of independent claims 1,13, and 25 should therefore be withdrawn and the 
case should be allowed. 

Nusbaum and Sun Do Not Teach 
Each and Every Element of the Claim 

To establish a prima facie case of obviousness, the proposed combination of Nusbaum 
and Sun must disclose all of applicants' claim limitations. In re Royka, 490F.2d 981, 
985, 180 USPQ 580, 583 (CCPA 1974). Independent claim 1 of the present application 
claims: 

1 . A method of remote direction of streaming digital content from a 

multiplicity of sources of digital information to a multiplicity of client 
devices the method implemented upon a network of digital computers, at 
least one of the digital computers comprising a content server upon which 
the steps of the method are implemented in computer memory and at least 
one computer processor, the method comprising the steps of: 

receiving digital content from the sources, the digital content having a 
multiplicity of digital formats; 

receiving, from a remote director, and storing in computer memory, 
remote director instructions, the remote director instructions including 
instructions for selections of digital content for inclusion in an output 
stream; 
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carrying out the remote director instructions, wherein carrying out the 
remote director instructions further comprises: 

selecting, in dependence upon the remote director's instructions, digital 
content for inclusion in an output stream; 

transcoding, in dependence upon the remote director's instructions, the 
digital content from sources into digital content having streaming format; 

including in an output stream, in dependence upon the remote director's 
instructions, digital content having streaming format; and 

communicating, in dependence upon the remote director's instructions, to 
at least one of the client devices the output stream. 

In rejecting claims 1,13, and 25, the Final Office Action at page 13 states that Nusbaum 
teaches "remote direction (e.g., figure 5, page 13)...." What Figure 5 on page 13 of 
Nusbaum actually depicts is a general "EJB environment and interaction with other 
components," where 'EJB' stands for Enterprise JavaBeans™. An Enterprise 
JavaBeans™ is a server-side object that conforms to the Enterprise JavaBeans™ 
Specification. The EJB specification describes the server-side component architecture of 
the Java 2 Enterprise Edition (' J2EE') platform that provides a framework for 
components to "plug in" to a server and extend that server's functionality. A server-side 
object that conforms to the Enterprise JavaBeans™ Specification is not remote direction 
of streaming digital content as claimed in the present application. Nusbaum's EJB 
environment and EJB interaction with other components therefore does not teach remote 
direction of streaming digital content as claimed in the present application. The Final 
Office Action does not produce references that teach each and every element of 
independent claims 1,13, and 25 and the rejections should be withdrawn. 
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In rejecting claims 1, 13 and 25, the Final Office Action at pages 13 and 14 also states 
that Nusbaum teaches: 

receiving, from a remote director, and storing in computer memory, 
remote director instructions (e.g., section 1.2.4, page 6, section 2.1.1.1, 
pages 31 and 32, section 8.1.8, page 417) 

the remote director instructions including instructions for selections of 
digital content for inclusion in an output streaming (e.g., section 1.2.4, 
page 6, sections 2.1.1.1, pages 31 and 32, section 8.1.8, page 417) 

carrying out the remote director instructions (e.g., section 1.2.4, page 6, 
section 2.1.1.1, pages 31 and 32, section 8.1.8, page 417), wherein 
carryout out the remote director instructions further comprises: 

selecting, in dependence upon the remote director's instructions, digital 
content for inclusion in an output stream (e.g., section 1.2.4, page 6) 

in dependence upon the remote director's instructions handling the digital 
content from sources (e.g. section 2.1.1.1, pages 31 and 32) 

including in an output streaming, in dependence upon the remote 
director's instructions, to at least one of the client devices the output 
stream (e.g. section 1.2.4, page 6) 

communicating, in dependence upon the remote director's instructions, to 
at least one of the client devices the output stream (e.g., section 1.2.4, page 
6). 
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That is, the Final Office Action relies on Nusbaum at section 1.2.4 on page 6, section 
2.1.1.1 on pages 31 and 32, and section 8.1.8 on page 417 to teach the following claim 
elements and limitations: 

• receiving, from a remote director, and storing in computer memory, remote 
director instructions, the remote director instructions including instructions for 
selections of digital content for inclusion in an output stream 

• carrying out the remote director instructions, wherein carrying out the remote 
director instructions further comprises 

• selecting, in dependence upon the remote director's instructions, digital content 
for inclusion in an output stream 

• transcoding, in dependence upon the remote director's instructions, the digital 
content from sources into digital content having streaming format 

• including in an output stream, in dependence upon the remote director's 
instructions, digital content having streaming format 

• communicating, in dependence upon the remote director's instructions, to at least 
one of the client devices the output stream 

What section 1.2.4 of Nusbaum actually teaches is an application programming interface 
('API') for a JavaServlet™. A servlet is a small Java computer program running in a 
server environment that allows a software developer to add dynamic content to a web 
server. Such Java technology for generating dynamic web pages is known as Java Server 
Pages, or 'JSP.' Section 2.1.1.1 of Nusbaum actually teaches an EJB server architecture 
that includes an "EJB server runtime," "EJB containers," and "Enterprise Java beans" 
that together provide services such as a "deployment tool," "naming services," and 
"security services." Section 8. 1 .8 of Nusbaum actually teaches a "DMT interface" for 
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"connecting] to one or more directory servers...," where 'DMT' stands for Directory 
Management Tool. Nusbaum's details of the JavaServlet™ API, EJB server architecture, 
and directory management tool interface have nothing whatsoever to do with the 
elements and limitations of the claims of the present invention for which the Final Office 
Action cites the Nusbaum references. In fact, Nusbaum never once mentions remote 
direction of streaming digital content, remote directors, or remote director instructions as 
claimed in the present application. The fact that Nusbaum makes some general 
references to network communications or that Sun makes general references to streaming 
media is completely insufficient to anticipate or suggest claim elements in the present 
application. Nusbaum's servlet API details, EJB server architecture, and directory 
management tool interface therefore does not teach the elements and limitations of the 
claims of the present application as cited in the Final Office Action. Because The Final 
Office Action does not produce references that teach each and every element of 
independent claims 1, 13, and 25, the rejections should be withdrawn. 

In rejecting claims 1,13, and 25, the Final Office Action at page 14 states that Sun 
teaches: 

Sun teaches streaming digital content and transcoding (e.g., transcoding 
the video contents, page 33) into digital content having streaming format 
objects and the digital content having a multiplicity of digital formats 
(e.g., streaming media as per remote instruction, page 4, MPEG, JPEG, 
etc., video formatted content, page 6). 

That is, the Final Office Action takes the position that pages 4, 6, and 33 of Sun teach 
"digital content having a multiplicity of digital formats..." and "transcoding... digital 
content from sources into digital content having streaming format. . ." as claimed in the 
present application. What page 4 of Sun actually teaches is definitions to some common 
terms used in streaming media including 'content type, 5 'media stream,' 'multiplex,' 
'track,' and so on. Page 6 of Sun merely discloses a chart of common video and audio 
formats. What page 33 of Sun actually teaches is a definition of transcoding as a 
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"process of converting each track of media data from one input format to another." Sun's 
definition of transcoding and of some common streaming media terms along with Sun's 
chart of common video and audio formats does not teach "digital content having a 
multiplicity of digital formats..." and "transcoding... digital content from sources into 
digital content having streaming format. . ." as claimed in the present application. The 
Final Office Action does not produce references that teach each and every element of 
independent claims 1 ? 13, and 25 and the rejections should be withdrawn. 



The Cited References Set Forth No Suggestion 
To Combine Nusbaum and Sun 



To establish a prima facie case of obviousness, there must be a suggestion or motivation 
to modify or combine Nusbaum and Sun. In re Vaeck, 947 F.2d 488, 493, 20 USPQ2d 
1438, 1442 (Fed. Cir. 1991). "The mere fact that references can be combined or modified 
does not render the resultant combination obvious unless the prior art also suggests the 
desirability of the combination." In re Mills, 916 F.2d 680, 16 USPQ2d 1430 (Fed. Cir. 
1990). The Examiner has not pointed to any disclosure in Nusbaum or Sun suggesting the 
desirability of the combination. Moreover, there is no possibility whatsoever that the 
Examiner could ever point to any disclosure in Nusbaum or Sun suggesting the 
desirability of the combination. Nusbaum in fact makes no mention whatsoever of 
remote direction of streaming digital content, remote directors, or remote director 
instructions, and therefore could not possibly suggest the desirability of the combination. 
In addition, no such suggestion occurs in Sun. Absent such a showing of desirability to 
combine Nusbaum and Sun, the Examiner has impermissibly used "hindsight" 
occasioned by Applicants' own teaching to reject the claims. In re Surko, 1 1 F.3d 887, 42 
U.S.P.Q.2d 1476 (Fed. Cir. 1997); In re Vaeck, 947 F.2d 488, 20 U.S.P.Q.2d 1438 (Fed. 
Cir. 1991); In re Gorman, 933 F.2d 982, 986, 18 U.S.P.Q.2d 1885, 1888 (Fed. Cir. 1991); 
In re Bond, 910 F.2d 831, 15 U.S.P.Q.2d 1566 (Fed. Cir. 1990); In re Laskowski, 871 F.2d 
115, 117, 10 U.S.RQ.2d 1397, 1398 (Fed. Cir. 1989). The proposed combination of 
Nusbaum and Sun therefore cannot possibly establish a prima facie case of obviousness. 
The objection should be withdrawn, and the case should be allowed. 
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There Is No Reasonable Expectation Of Success In The 
Proposed Combination Of Nusbaum And Sun 

To establish a prima facie case of obviousness, there must be a reasonable expectation of 
success in the proposed combination of Nusbaum and Sun. In re Merck & Co., Inc., 800 
F.2d 1091, 1097, 231 USPQ 375, 379 (Fed. Cir. 1986). The Examiner has not pointed to 
any disclosure in Nusbaum or Sun suggesting any expectation of success in such a 
combination. In fact, there can be no reasonable expectation of success in the proposed 
combination of Nusbaum and Sun because Nusbaum and Sun cannot be combined to 
provide remote direction of streaming digital content as claimed in the present 
application. The Final Office Action bases this rejection on portions of Nusbaum that 
includes Figure 5 on page 13, section 1.2.4 on page 6, section 2.1.1.1 on pages 31 and 32, 
and section 8. 1 .8 on page 417. As explained above, these references to Nusbaum teach 
an EJB execution environment and a kind of dynamic web page technology known as 
Java Server Pages or 'JSP' The Final Office Action also bases this rejection on portions 
of Sun that includes page 4, page 6, and page 33, which as explained above, merely 
provide some definitions regarding streaming media as the terms are used in the Java 
Media Framework. As described in Nusbaum, dynamic web page technology is methods 
and systems for building server pages on the fly. Dynamic web pages generally, and JSPs 
in particular, is not streaming media and does not combine with streaming media to 
provide remote direction of streaming digital content as claimed in the present 
application. The proposed combination of Nusbaum and Sun therefore cannot support a 
prima facie case of obviousness. The rejection should be withdrawn, and the case should 
be allowed. 

Nusbaum Teaches Away From the 
Claims of the Present Application 

Turning now to the substance of Nusbaum, Nusbaum actually teaches away from the 
current application. Teaching away from the claims is a per se demonstration of lack of 
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prima facie obviousness. In re Dow Chemical Co., 837 F.2d 469, 5 U.S.P.Q.2d 1529 
(Fed. Cir. 1988); In re Fine, 837 F.2d 1071, 5 U.S.P.Q.2d 1596 (Fed. Cir. 1988); In re 
Neilson, 816 F.2d 1567, 2 U.S.P.Q.2d 1525 (Fed. Cir. 1987). Nusbaum discloses 
dynamic web page technology with no mention of remote directors or remote director 
instructions. Without even mentioning remote directors or remote director instructions, 
there could be no impulse on the part of developers of dynamic web page technology to 
incorporate remote directors or remote director instructions into dynamic web page 
technology. By effecting dynamic web page technology alone, with no hint or suggestion 
that remote directors or remote director instructions might even exist, Nusbaum teaches 
away from the combination with Sun proposed in the Final Office Action. Because 
Nusbaum teaches away from the Applicants' claims, the proposed modification of 
Nusbaum with Sun cannot support a prima facie case of obviousness. The rejection of 
Applicants' claims should be withdrawn, and the case should be allowed. 

Nusbaum Cannot be a Reference Against the Claims of the Present 
Application Because Nusbaum Represents Nonanalogous Art 

Nusbaum cannot be a reference against the claims of the present application because 
Nusbaum represents nonanalogous art within the meaning of In Re Horn, In re Clay, and 
In re Oeitker. In re Horn, 203 USPQ 969 (CCPA 1 979), In re Clay, 966 F.2d 656, 23 
USPQ2d 1058 (Fed. Cir. 1992), In re Oeticker, 977 F.2d 1443, 24 USPQ2d 1443 (Fed. 
Cir. 1992). The field of the inventors' effort in this case is remote direction of streaming 
digital content. The present application claims, among other things, receiving digital 
content, receiving remote director instructions, and carrying out the remote director 
instructions. The field of Nusbaum is dynamic web pages for the World Wide Web - 
which clearly has nothing to do with the technical field of the present application. 
Nusbaum therefore is not within the field of the inventor's endeavor in this case. 

Because Nusbaum is not within the field of the inventor's endeavor in this case, there can 
be no basis for believing that Nusbaum as a reference would have been considered by one 
skilled in the particular art working on the relevant problem to which this invention 
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pertains. That is, there would be no reason for an inventor concerned with remote 
direction of streaming digital content to search for art regarding dynamic generation of 
web pages. The two simply have nothing to do with one another. Nusbaum as a 
reference therefore is not reasonably pertinent to the particular problem with which the 
inventors were involved in the present case and is not available as a reference against the 
present application. Applicants respectfully propose that for this reason alone the 
rejection of the present claims should be withdrawn, and the claims should be allowed. 

Conclusion 

All claims in the present case stand rejected under 35 U.S.C § 103(a). Independent claims 
1, 13, and 25 stand rejected under 35 U.S.C § 103(a) over Nusbaum in view of Sun. The 
combination of Nusbaum and Sun fails to establish a prima face case of obviousness. 
The applicants have demonstrated that it is incorrect to reject the independent claims 1, 
13, and 25 under 35 U.S.C § 103(a). The dependent claims of the present application 
include each and every element and limitation of the independent claims from which they 
depend. Because the Final Office Action cites only the combination of Nusbaum and 
Sun to teach or suggest each and every element of the independent claims and because all 
the independent claims stand, Applicants respectfully propose that all the dependent 
claims in the present case stand. The rejection of all the claims 1-36 should therefore be 
withdrawn, and the claims should be allowed. Applicants respectfully traverse the 
rejection of claims 1-36 and request reconsideration of claims 1-36 in light of the present 
remarks. 

APPPLICANTS' RESPONSE TO EXAMINER'S RESPONSE TO APPLICANTS' 
RESPONSE TO THE FIRST OFFICE ACTION DATED SEPTEMBER 24, 2004 

The Final Office Action responds to Applicants' Response to First Office Action of 
September 24, 2004 ("First Office Action") with the following arguments. First, 
Nusbaum and Sun set forth a suggestion or motivation to combine Nusbaum and Sun. 
Second, there is a reasonable expectation of success in the combination of Nusbaum and 
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Sun. Third, Nusbaum and Sun teach or suggest each and every element and limitation of 
the Applicants' claims. Finally, Nusbaum is analogous art because it is in the field of 
Applicants' endeavor or reasonably pertinent to the particular problem with which the 
Applicants were concerned. Applicants respectfully traverse each of the responses in the 
Final Office Action to Applicants' Response to the First Office Action and respond 
below in detail to the new arguments set forth in the Final Office Action. 

The Cited References Set Forth No Suggestion Or 
Motivation To Combine Nusbaum And Sun 

The Final Office Action at pages 2 and 3 argues that Nusbaum and Sun are properly 
combined for an obviousness rejection under 35 U.S.C. § 103 on the grounds that: 

Nusbaum teaches a method, a system, and a computer program product to 
implement remote direction (e.g., figure 5, page 13) of handling 
information from a multiplicity of sources of digital information to a 
multiplicity of client devices (e.g., section 1.2.4, page 6, section 2.1.1.1, 
pages 31 and 32, section 8.1.8, page 417) the method implemented upon a 
network of digital computers (e.g., figure 5, page 13, at least one of the 
digital computers comprising a content server upon which the steps of the 
method are implemented (e.g., section 1.2.4, page 6, section 2.1.1.1, pages 
31 and 32, section 8.1.8, page 417) in computer memory and at least one 
computer processor (e.g., server containing web content, page 13) the 
method comprising the steps of: receiving digital content from the sources 
(e.g., section 1.2.4, page 6, section 2.1.1.1, pages 31 and 32, section 8.1.8, 
page 417) receiving, from a remote director, and storing in computer 
memory, remote director instructions (e.g. 1.2.4, page 6, section 2.1.1.1, 
pages 31 and 32, section 8.1.8, page 417), the remote director instructions 
including instructions for selections of digital content for inclusion in an 
output streaming (e.g., section 1.2.4, page 6, section 2.1.1.1, pages 31 and 
32, section 8.1.8, page 417); carrying out the remote director instructions 
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(e.g. section 1.2.4, page 6, section 2.1.1.1, pages 31 and 32, section 8.1.8, 
page 417). Sun teaches well known concept of streaming digital content 
and transcoding (e.g., transcoding the video contents, page 33) into digital 
content having streaming format objects and the digital content having a 
multiplicity of digital formats (e.g., streaming media, page 4, MPEG, 
JPEG, etc., video formatted content, page 6). 

That is, the Final Office Action responds to Applicants' argument that there is no 
suggestion or motivation to combine Nusbaum and Sun by stating that Nusbaum and Sun 
teach various elements and limitations of the independent claims. As explained in detail 
above, the cited references in fact do not teach remote direction of streaming digital 
content from a multiplicity of sources of digital information to a multiplicity of client 
devices as claimed in the present application. Nusbaum generally teaches a kind of 
dynamic web page technology known as Java Server Pages. What Nusbaum teaches 
specifically at Figure 5 is an Enterprise JavaBean™ environment and its interaction with 
other network components. Section 1.2.4 of Nusbaum specifically teaches an application 
programming interface (' APF) for a JavaServlet™. Section 2.1.1.1 of Nusbaum 
specifically teaches an Enterprise JavaBean™ server architecture, while section 8.1.8 of 
Nusbaum specifically teaches a Directory Management Tool interface. Sun generally 
teaches the Java Media API, an application programming interface for deliver of time- 
based media. What Sun teaches specifically at pages 4, 6, and 33 is a general description 
of streaming media and content types, common audio formats, and a general description 
of media player operations. Not only do the cited portions of the references fail to 
disclose or suggest elements of the present claims, even if they did so, the Final Office 
Action cannot arbitrarily pick and choose with massive hindsight elements of Applicants' 
claims from Java Server Pages and the Java Media API and use them as a basis to 
conclude the present claims invalid for obviousness. For these reasons, Applicants 
continue to assert that there is no suggestion or motivation to combine Nusbaum and Sun. 
The proposed combination of Nusbaum and Sun therefore cannot support a prima facie 
case of obviousness. The rejections to claims 1-36 should be withdrawn, and the case 
should be allowed. 
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The Final Office Action at page 2 citing In re Keller, 642 R2d 413, 425, 208 USPQ 871, 
881 (CCPA 1981) and In re Young, 927 F.2d 588, 591 18 USPQ2d 1089, 1091 (Fed. Cir. 
1991), also argues that: 

the test for obviousness is not whether the features of a secondary 
reference may be bodily incorporated into the structure of a primary 
reference. It is also not that the claimed invention must be expressly 
suggested in any one or all of the references. Rather, the test is what the 
combined teachings of the references would have suggested to those of 
skill in the art. 

In this way, the Final Office Action implicitly argues that there is no need for the 
Examiner to demonstrate that the references provide motivation or suggestion to combine 
or that there is any reasonable expectation of success in combining the references so long 
as elements of the present claims are disclosed in the references. 

As the Commissioner is well aware, however, such is not the law. The mere fact that 
references can be combined or modified does not render the resultant combination 
obvious unless the prior art also suggests the desirability of the combination. In re Mills, 
916 R2d 680, 16 USPQ2d 1430 (Fed. Cir. 1990). In fact, the requirement of a prima 
facie case of obviousness places a burden on the examiner to provide some suggestion of 
the desirability of doing what the inventor has done. "To support the conclusion that the 
claimed invention is directed to obvious subject matter, either the references must 
expressly or impliedly suggest the claimed invention or the examiner must present a 
convincing line of reasoning as to why the artisan would have found the claimed 
invention to have been obvious in light of the teachings of the references." Ex parte 
Clapp, 227 USPQ 972, 973 (Bd. Pat. App. & Inter. 1985). When the motivation to 
combine the teachings of the references is not immediately apparent, it is the duty of the 
examiner to explain why the combination of the teachings is proper. Ex parte Skinner, 2 
USPQ2d 1788 (Bd. Pat. App. & Inter. 1986); MPEP § 2142. 
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The Final Office Action merely continues the practice begun in the First Office Action of 
pointing to elements of method and system in its cited references and stating that they are 
the same things claimed in the present patent application. The Final Office Action makes 
no substantive attempt whatsoever to present a prima facie case of obviousness by 
pointing to express or implicit suggestion to combine in the references themselves or by 
explaining or providing any basis for concluding that persons of skill in the art would be 
moved to combine the references. For these reasons also, Applicants continue to assert 
that the cited references do not contain a suggestion or motivation to combine. The 
proposed combination of Nusbaum and Sun therefore cannot support a prima facie case 
of obviousness. The rejections to claims 1-36 should be withdrawn, and the case should 
be allowed. 

There Is No Reasonable Expectation Of Success In The 
Combination Of Nusbaum And Sun 

In response to Applicants' Response to the First Office Action, the Final Office Action at 
pages 3 and 4 argues that there is a reasonable expectation of success in the combination 
of Nusbaum and Sun. The Final Office Action does not, however, provide any new basis 
for this assertion other than stating that Nusbaum and Sun teach various elements and 
limitations of the independent claims. As explained in detail above, the cited references 
in fact do not teach remote direction of streaming digital content from a multiplicity of 
sources of digital information to a multiplicity of client devices as claimed in the present 
application. Nusbaum generally teaches a kind of dynamic web page technology known 
as Java Server Pages. Sun generally teaches the Java Media API, an application 
programming interface for delivery of time-based media. The dynamic web page 
technology of Nusbaum for building adhoc server pages is not related to the Java API for 
time-based media of Sun. In fact, the technology for building dynamic web pages is 
entirely different from a Java API for time-based media. JSPs generate documents 
viewable in a web browser, while the API for time-based media provide a Java class 
architecture to software developers. Combining Nusbaum's Java Server Pages and Sun's 
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Java Media API does not provide remote direction of streaming digital content from a 
multiplicity of sources of digital information to a multiplicity of client devices as claimed 
in the present application. For these reasons, Applicants continue to assert that there is 
therefore no reasonable expectation of success in the proposed combination of Nusbaum 
and Sun. The proposed combination of Nusbaum and Sun therefore cannot support a 
prima facie case of obviousness. The rejections to claims 1-36 should be withdrawn, and 
the case should be allowed. 



Nusbaum And Sun Do Not Teach 
Each and Every Element of the Claim 



The Final Office Action at page 5 again argues that Nusbaum and Sun teach each and 
every element of independent claims 1,13, and 25 by reciting portions of Nusbaum and 
Sun mentioned above in this Brief. To establish a prima facie case of obviousness, the 
proposed combination of Nusbaum and Sun must teach all of Applicants' claim 
limitations. In re Royka, 490F.2d 981, 985, 180 USPQ 580, 583 (CCPA 1974). As 
discussed in detail above, the combination of Nusbaum and Sun does not teach each and 
every element of the independent claims in the present case. The Final Office Action 
therefore cannot establish a prima facie case for obviousness of claims 1, 23, and 45 
under 35 U.S.C. § 103. The dependent claims of the present application include each and 
every element and limitation of the independent claims from which they depend. 
Because the Final Office Action cites only the combination of Nusbaum and Sun to teach 
or suggest each and every element of the independent claims and because all the 
independent claims stand, Applicants respectfully propose that all the dependent claims 
in the present case stand. The proposed combination of Nusbaum and Sun therefore 
cannot support a prima facie case of obviousness. The rejections to claims 1-36 should 
be withdrawn, and the case should be allowed. 
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Nusbaum Is Not Analogous Art Because It Is Neither In The Field Of Applicants' 
Endeavor Nor Reasonably Pertinent To The Particular Problem 
With Which The Applicants Were Concerned 



In response to Applicants' First Office Action, the Final Office Action at pages 6 and 7 
argues that Nusbaum is analogous art available for rejecting the claims of the present 
application. The Final Office Action asserts that Nusbaum is in the field of Applicants' 
endeavor or reasonably pertinent to the particular problem with which the Applicants 
were concerned. In support for this assertion, the Final Office Action at page 6 and 7 
only states that Nusbaum and Sun teach various elements and limitations of the 
independent claims. As explained in detail above, the cited references in fact do not 
teach remote direction of streaming digital content from a multiplicity of sources of 
digital information to a multiplicity of client devices as claimed in the present 
application. Nusbaum generally teaches a kind of dynamic web page technology known 
as Java Server Pages. Sun generally teaches the Java Media API, an application 
programming interface for delivery of time-based media. Without more, Nusbaum' s Java 
Server Pages does not place Nusbaum in the field of Applicants' endeavor or make 
Nusbaum reasonably pertinent to the particular problem with which the Applicants were 
concerned, such concern being, remote direction of streaming digital content as claimed 
in the present application. 

In addition, Applicants respectfully propose that Nusbaum cannot be a reference against 
the claims of the present application because Nusbaum actually represents nonanalogous 
art within the meaning of In Re Horn, Clay, and Oeitker. In re Horn, 203 USPQ 969 
(CCPA 1979), In re Clay, 966 F.2d 656, 23 USPQ2d 1058 (Fed. Cir. 1992), In re 
Oeticker, 977 F.2d 1443, 24 USPQ2d 1443 (Fed. Cir. 1992). The field of the inventors' 
effort in this case is remote direction of streaming digital content. The present 
application claims, among other things, receiving digital content, receiving remote 
director instructions, and carrying out the remote director instructions. The field of 
Nusbaum is dynamic web pages for the World Wide Web - which clearly has nothing to 
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do with the technical field of the present application. Nusbaum therefore is not within the 
field of the inventor's endeavor in this case. 

Because Nusbaum is not within the field of the inventor's endeavor in this case, there can 
be no basis for believing that Nusbaum as a reference would have been considered by one 
skilled in the particular art working on the relevant problem to which this invention 
pertains. That is, there would be no reason for an inventor concerned with remote 
direction of streaming digital content to search for art regarding dynamic generation of 
web pages. The two simply have nothing to do with one another. Nusbaum as a 
reference therefore is neither within the field of the Applicants' endeavor nor reasonably 
pertinent to the particular problem with which the inventors were involved in the present 
case. Nusbaum therefore is not available as a reference against the present application. 
Applicants respectfully propose that for this reason alone the rejection of the present 
claims 1-36 should be withdrawn, and the claims should be allowed. 



Conclusion 



Applicants traverse each of the arguments in the Final Office Action responding to 
Applicants' Response to First Office Action. Applicants demonstrate that the cited 
references in the Final Office Action set forth neither a suggestion nor motivation to 
combine Nusbaum and Sun. Furthermore, there is no reasonable expectation of success 
in the combination of Nusbaum and Sun. In addition, Nusbaum and Sun do not teach or 
suggest each and every element and limitation of the Applicants' claims. Applicants also 
demonstrate that Nusbaum represents nonanalogous art. Applicants' therefore 
respectfully traverse each rejection individually of claims 1-36. 
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In view of the forgoing arguments, reversal on all grounds of rejection is requested. 

The Commissioner is hereby authorized to charge or credit Deposit Account No. 09-0447 
for any fees required or overpaid. 



Date: November 30. 2005 



By: 



Respectfully submitted, 




Biggers 



Reg. No. 44,537 

Biggers & Ohanian, LLP 

P.O. Box 1469 

Austin, Texas 78767-1469 

Tel. (512) 472-9881 

Fax (5 12) 472-9887 

ATTORNEY FOR APPELLANTS 
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APPENDIX OF CLAIMS 
ON APPEAL IN PATENT APPLICATION OF 
WILLIAM K. BODIN, ETAL., SERIAL NO. 09/881,915 



CLAIMS 
What is claimed is: 

1 . A method of remote direction of streaming digital content from a multiplicity of 
sources of digital information to a multiplicity of client devices the method 
implemented upon a network of digital computers, at least one of the digital 
computers comprising a content server upon which the steps of the method are 
implemented in computer memory and at least one computer processor, the 
method comprising the steps of: 

receiving digital content from the sources, the digital content having a multiplicity 
of digital formats; 

receiving, from a remote director, and storing in computer memory, remote 
director instructions, the remote director instructions including instructions for 
selections of digital content for inclusion in an output stream; 

carrying out the remote director instructions, wherein carrying out the remote 
director instructions further comprises: 
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selecting, in dependence upon the remote director's instructions, digital content 
for inclusion in an output stream; 

transcoding, in dependence upon the remote director's instructions, the digital 
content from sources into digital content having streaming format; 

including in an output stream, in dependence upon the remote director's 
instructions, digital content having streaming format; 

communicating, in dependence upon the remote director's instructions, to at least 
one of the client devices the output stream. 

The method of claim 1, wherein the client devices comprise client device 
attributes, said transcoding further comprising transcoding in dependence upon 
the client device attributes. 

The method of claim 2 wherein client device attributes include device type, screen 
size, frame rate, and audio status. 

The method of claim 1 wherein the remote director comprises a personal 
computer coupled through a network to the content server, the method further 
comprising: 

sending from the remote director to the content server remote director 
instructions, further comprising invoking through URLs displayed on a terminal 
of the remote director member methods in servlets installed on the content server. 

The method of claim 4 wherein the invoking through URLs further comprises 
invoking through each URL a single member method in a servlet. 

The method of claim 5 wherein the single member method is programmed to 
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carry out a single remote director instruction. 

The method of claim 5 wherein the single member method is implemented as a 
Java thread-level URL dispatch routine. 

The method of claim 4 wherein the remote director instruction comprises an 
instruction to select for transcoding and streaming digital content from a specific 
source. 

The method of claim 1 further comprising the steps of: 

registering a user for a service, the service identified by a service identification 
code, the service comprising at least one output stream; 

logging in the user for the service, logging in the user further comprising 
assigning values to user login attributes, the user login attributes comprising user 
identification, device type, network address, and a tier; 

assigning a tier value in dependence upon the device type and the service 
identification code; 

wherein the selections are dependent upon the tier; 

wherein transcoding further comprises transcoding in dependence upon the tier; 
and 

wherein communicating to at least one of the client devices the output stream 
further comprises communicating the output stream to the network address. 

The method of claim 6 wherein: 
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registering a user further comprises creating a service registration record 
comprising service registration attributes comprising user id, service id and 
service subscription level; and 

assigning a tier value further comprises assigning a tier value in dependence upon 
the service subscription level. 

The method of claim 1 further comprising the steps of: 

registering a user for an event, the event identified by an event identification code, 
the event comprising at least one output stream, at least one source, a start date 
and a start time; 

logging in the user for the event, logging in the user further comprising assigning 
values to user login attributes, the user login attributes comprising user 
identification, device type, network address, and a tier; 

assigning a tier value in dependence upon the device type and the event 
identification code; 

wherein the selections are dependent upon the tier; 

wherein transcoding further comprises transcoding in dependence upon the tier; 
and 

wherein communicating to at least one of the client devices the output stream 
further comprises communicating the output stream to the network address. 

The method of claim 5 wherein: 
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registering a user further comprises creating an event registration record 
comprising event registration attributes comprising user id, event id, event 
subscription level, start date, and start time; and 

assigning a tier value further comprises assigning a tier value in dependence upon 
the event subscription level. 

13. A system for remote direction of streaming digital content from a multiplicity of 
sources of digital information to a multiplicity of client devices the system 
implemented upon a network of digital computers, at least one of the digital 
computers comprising a content server upon which the system is implemented in 
computer memory and upon at least one computer processor, the system 
comprising: 

means for receiving digital content from the sources, the digital content having a 
multiplicity of digital formats; 

means for receiving, from a remote director, and storing in computer memory, 
remote director instructions, the remote director instructions including 
instructions for selections of digital content for inclusion in an output stream; 

means for transcoding the digital content from sources into digital content having 
streaming format; 

means for including in an output stream, in dependence upon the remote 
director's instructions, digital content having streaming format; 

means for communicating to at least one of the client devices the output stream. 

14. The system of claim 13, wherein the client devices comprise client device 
attributes, said means for transcoding further comprising means for transcoding in 
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dependence upon the client device attributes. 

15. The system of claim 14wherein client device attributes include device type, screen 
size, frame rate, and audio availability. 

16. The system of claim 13 wherein the remote director comprises a personal 
computer coupled through a network to the content server, the system further 
comprising: 

means for sending from the remote director to the content server remote director 
instructions, further comprising means for invoking through URLs displayed on a 
terminal of the remote director member methods in servlets installed on the 
content server. 

17. The system of claim 16 wherein the means for invoking through URLs further 
comprises means for invoking through each URL a single member method in a 
servlet. 

1 8. The system of claim 1 7 wherein the single member method is programmed to 
carry out a single remote director instruction. 

19. The system of claim 17 wherein the single member method is implemented as a 
thread-level Java URL dispatch routine. 

20. The system of claim 16 wherein the remote director instruction comprises an 
instruction to select for transcoding and streaming digital content from a specific 
source. 

21. The system of claim 13 further comprising: 
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means for registering a user for a service, the service identified by a service 
identification code, the service comprising at least one output stream; 

means for logging in the user for the service, said means for logging in the user 
further comprising means for assigning values to user login attributes, the user 
login attributes comprising user identification, device type, network address, and 
a tier; 

means for assigning a tier value in dependence upon the device type and the 
service identification code; 

wherein the selections are dependent upon the tier; 

wherein means for transcoding further comprises means for transcoding in 
dependence upon the tier; and 

wherein means for communicating to at least one of the client devices the output 
stream further comprises means for communicating the output stream to the 
network address. 

22. The system of claim 1 8wherein: 

means for registering a user further comprises means for creating a service 
registration record comprising service registration attributes comprising user id, 
service id and service subscription level; and 

means for assigning a tier value further comprises means for assigning a tier value 
in dependence upon the service subscription level. 

23. The system of claim 1 3further comprising: 
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means for registering a user for an event, the event identified by an event 
identification code, the event comprising at least one output stream, at least one 
source, a start date and a start time; 

means for logging in the user for the event, logging in the user further comprising 
assigning values to user login attributes, the user login attributes comprising user 
identification, device type, network address, and a tier; 

means for assigning a tier value in dependence upon the device type and the event 
identification code; 

wherein the selections are dependent upon the tier; 

wherein means for transcoding further comprises means for transcoding in 
dependence upon the tier; and 

wherein means for communicating to at least one of the client devices the output 
stream further comprises means for communicating the output stream to the 
network address. 

24. The system of claim 1 7 wherein: 

means for registering a user further comprises means for creating an event 
registration record comprising event registration attributes comprising user id, 
event id, event subscription level, start date, and start time; and 

means for assigning a tier value further comprises means for assigning a tier value 
in dependence upon the event subscription level. 



25. A computer program product for remote direction of streaming digital content 
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from a multiplicity of sources of digital information to a multiplicity of client 
devices the system implemented upon a network of digital computers, at least one 
of the digital computers comprising a content server upon which the system is 
implemented in computer memory and upon at least one computer processor, the 
computer program product comprising: 

a recording medium; 

means, recorded on the recording medium, for receiving digital content from the 
sources, the digital content having a multiplicity of digital formats; 

means, recorded on the recording medium, for receiving, from a remote director, 
and storing in computer memory, remote director instructions, the remote director 
instructions including instructions for selections of digital content for inclusion in 
an output stream; 

means, recorded on the recording medium, for transcoding the digital content 
from sources into digital content having streaming format; 

means, recorded on the recording medium, for including in an output stream, in 
dependence upon the remote director's instructions, digital content having 
streaming format; 

means, recorded on the recording medium, for communicating to at least one of 
the client devices the output stream. 

The computer program product of claim 25, wherein the client devices comprise 
client device attributes, said means for transcoding further comprising means for 
transcoding in dependence upon the client device attributes. 

The computer program product of claim 26 wherein client device attributes 
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include device type, screen size, frame rate, and audio availability. 

28. The computer program product of claim 25 wherein the remote director comprises 
a personal computer coupled through a network to the content server, the system 
further comprising: 

means, recorded on the recording medium, for sending from the remote director to 
the content server remote director instructions, further comprising means, 
recorded on the recording medium, for invoking through URLs displayed on a 
terminal of the remote director member methods in servlets installed on the 
content server. 

29. The computer program product of claim 28 wherein the means for invoking 
through URLs further comprises means for invoking through each URL a single 
member method in a servlet. 

30. The computer program product of claim 29 wherein the single member method is 
programmed to carry out a single remote director instruction. 

3 1 . The computer program product of claim 29 wherein the single member method is 
implemented as a thread-level Java URL dispatch routine. 

32. The computer program product of claim 28 wherein the remote director 
instruction comprises an instruction to select for transcoding and streaming digital 
content from a specific source. 

33. The computer program product of claim 25further comprising: 

means, recorded on the recording medium, for registering a user for a service, the 
service identified by a service identification code, the service comprising at least 
one output stream; 
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means, recorded on the recording medium, for logging in the user for the service, 
said means for logging in the user further comprising means for assigning values 
to user login attributes, the user login attributes comprising user identification, 
device type, network address, and a tier; 

means, recorded on the recording medium, for assigning a tier value in 
dependence upon the device type and the service identification code; 

wherein the selections are dependent upon the tier; 

wherein means for transcoding further comprises means for transcoding in 
dependence upon the tier; and 

wherein means for communicating to at least one of the client devices the output 
stream further comprises means for communicating the output stream to the 
network address. 

The computer program product of claim 30 wherein: 

means for registering a user further comprises means for creating a service 
registration record comprising service registration attributes comprising user id, 
service id and service subscription level; and 

means for assigning a tier value further comprises means for assigning a tier value 
in dependence upon the service subscription level. 

The computer program product of claim 25further comprising: 
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means, recorded on the recording medium, for registering a user for an event, the 
event identified by an event identification code, the event comprising at least one 
output stream, at least one source, a start date and a start time; 

means, recorded on the recording medium, for logging in the user for the event, 
logging in the user further comprising assigning values to user login attributes, the 
user login attributes comprising user identification, device type, network address, 
and a tier; 

means, recorded on the recording medium, for assigning a tier value in 
dependence upon the device type and the event identification code; 

wherein the selections are dependent upon the tier; 

wherein means for transcoding further comprises means for transcoding in 
dependence upon the tier; and 

wherein means for communicating to at least one of the client devices the output 
stream further comprises means for communicating the output stream to the 
network address. 

The computer program product of claim 29 wherein: 

means for registering a user further comprises means for creating an event 
registration record comprising event registration attributes comprising user id, 
event id, event subscription level, start date, and start time; and 

means for assigning a tier value further comprises means for assigning a tier value 
in dependence upon the event subscription level. 
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Abstract. This paper presents OpenJava, which is a macro system that 
we have developed for Java. With traditional macro systems designed for 
non object-oriented languages, it is difficult to write a number of macros 
typical in object-oriented programming since they require the ability to 
access a logical structure of programs. One of the drawbacks of tradi- 
tional macro systems is that abstract syntax trees are used for repre- 
senting source programs. This paper first points out this problem and 
then shows how OpenJava addresses this problem. A key idea of Open- 
Java is to use metaobjects, which was originally developed for reflective 
computing, for representing source programs. 



1 Introduction 

Reflection is a technique for changing the program behavior according to another 
program. From software engineering viewpoint, reflection is a tool for separation 
of concerns and thus it can be used for letting programmers write a program 
with higher-level abstraction and with good modularity. For example, a number 
of reflective systems provide metaobjects for intercepting object behavior, that 
is, method invocations and field accesses. Those metaobjects can be used for 
weaving several programs seprately written from distinct aspects, such as an 
application algorihtm, distribution, resource allocation, and user interface, into 
a single executable program. 

However, previous reflective systems do not satisfy all the requirements in 
software engineering. Although the abstraction provided by the metaobjects for 
intercepting object behavior is easy to understand and use, they can be used for 
implementing only limited kinds of separation of concerns. Moreover, this type 
of reflection often involves runtime penalties. Reflective systems should enable 
more fine-grained program weaving and perform as much reflective computation 
as possible at compile time for avoiding runtime penalities. 

On the other hand, a typical tool for manipulating a program at compile time 
has been a macro system. It performs textual substitution so that a particualr 
aspect of a program is separated from the rest of that program. For example, 
the C/C++ macro system allows to separate the definition of a constant value 



from the rest of a program, in which that constant value is used in a number 
of distinct lines. The Lisp macro system provides programable macros, which 
enables more powerful program manipulation than the C/C++ one. Also, since 
macro expansion is done at compile time, the use of macros does not imply any 
runtime penalties. However, the abstraction provided by traditional macro sys- 
tems is not sophisticated; since macros can deal with only textual representation 
of a program, program manipulation depending on the semantic contexts of the 
program cannot be implemented with macros. 

This paper proposes a macro system integrating good features of the reflective 
approach, in other words, a compile-time reflective system for not only behav- 
ioral reflection but also structural reflection. A key idea of our macro system, 
called OpenJava, is that macros (meta programs) deal with class metaobjects 
representing logical entities of a program instead of a sequence of tokens or ab- 
stract syntax trees (ASTs). Since the class metaobjects abstract both textual 
and semantic aspects of a program, macros in OpenJava can implement more 
fine-grained program weaving than in previous reflective systems. They can also 
access semantic contexts if they are needed for macro expansion. This paper 
presents that OpenJava can be used to implement macros for helping complex 
programmings with a few design patterns. 

In the rest of this paper, section 2 presents a problem of ordinary macro sys- 
tems and section 3 discusses the design and implementation of OpenJava, which 
addresses this problem. We compare OpenJava with related work in section 4. 
Finally, section 5 concludes this paper. 



2 Problems with Ordinary Macros 

Macro systems have been typical language-extension mechanisms. With C/C++ 's 
#def ine macro system, programmers can specify a symbol or a function call to 
be replaced with another expression, although this replacement is simple token- 
based substitution. In Common Lisp, programmers can write more powerful 
macros. However, even such powerful macros do not cover all requirements of 
00 languages programming. 



2.1 Programmable Macros 

Macros in Common Lisp are programmable macros. They specify how to replace 
an original expression in Common Lisp itself. A macro function receives an 
AST (abstract syntax tree) and substitutes it for the original expression. Since 
this macro system is powerful, the object system of Common Lisp (CLOS) is 
implemented with this macro system. 

Programmable macros have been developed for languages with more complex 
syntax like C. MS 2 [19] is one of those macro systems for C. Macro functions are 
written in an extended C language providing special data structure representing 
ASTs. The users of MS 2 can define a new syntax and how it is expanded into 



a regular C syntax. The parameter that a macro function receives is an AST of 
the code processed by that macro function. 

One of the essential issue in designing a programmable macro system is a 
data structure representing an original source program. Another essential issue 
is how to specify where to apply each macro in a source program. For the former 
most systems employed ASTs^ For the latter, several mechanisms were proposed' 

In Common Lisp and MS 2 , a macro is applied to expressions or statements 
beginning with the trigger word specified by the macro. For example if the 
trigger word is unless, all expressions beginning with unless are expanded by 
that macro. In this way, they cannot use macros without the trigger words For 
instance, it is impossible to selectively apply a macro to only + expressions for 
adding string objects. 

Some macro systems provide fine-grained control of where to apply a macro. 
In A* [14], a macro is applied to expressions or statements matching a pattern 
specified in the BNF. In EPP[9], macros are applied to a specified syntax ele- 
ments like if statements or + expressions. There's no need to put any trigger 
word in front of these statements or expressions. 



2.2 Representation of Object-Oriented Programs 

Although most of macro systems have been using ASTs for representing a source 
program, ASTs are not the best representation for all macros: some macros typ- 
ical in 00 programming require a different kind of representation. ASTs are 
purely textual representation and independent of logical or contextual informa- 
tion of the program. For example, if an AST represents a binary expression, the 
AST tells us what the operator and the operands are but it never tells us the 
types of the operands. Therefore, writing a macro is not possible with ASTs 
if the macro expansion depends on logical and contextual information of that 
binary expression. 

There is a great demand for the macros depending on logical and contextual 
information in 00 programming. For example, some of design patterns[6] re- 
quire relatively complicated programming. They often require programmers to 
repeatedly write similar code.fl] To help this programming, several researchers 
have proposed to extend a language to provide new language constructs special- 
ized for particular patterns [1, 7], Those constructs should be implemented with 
macros although they have been implemented so far by a custom preprocessor. 
This is because macros implementing those constructs depend on the logical and 
contextual information of programs and thus they are not implementable on top 
of the traditional AST-based macro systems. 

Suppose that we write a macro for helping prograrnming with the Ob- 
server^] pattern, which is for describing one-to-many dependency among ob- 
jects. This pattern is found in the Java standard library although it is called 
the event-and-listener model. For example, a Java program displays a menu bar 
must define a listener object notified of menu-select events. The listener object 
is an instance of a class MyMenu Listener implementing interface Menu Listener: 



class MyMenuListener implements MenuListener { 
void menuSelected(MenuEvent e) { . . } 
void menuDeselected(MenuEvent e) { return; } 
void menuCaaceled(MenuEvent e) { return: > 

> 

This class must declare all the methods for event handling even though some 
events, such as the menu cancel event, are simply ignored. 

We write a macro for automating declaration of methods for handling ignored 
events. If this macro is used, the definition of MyMenuListener should be re- 
written into: 

class MyMenuListener follows ObserverPattern 
implements MenuListener 

t 

void menuSelected(MenuEvent e) { . . } 

} 

The follows clauses specifies that our macro ObserverPattern is applied to this 
class definition. The declarations of menuDes el ectedO andmenuCanceledO are 
automated. This macro first inspects which methods declared in the interface 
MenuListener are not implemented in the class MyMenuListener. Then it inserts 
the declarations of these methods in the class MyMenuListener. 

Writing this macro is difficult with traditional AST-based macro systems 
since it depends on the logical information of the definition of the class My- 
MenuListener. If a class definition is given as a large AST, the macro program 
must interpret the AST and recognize methods declared in MenuListener and 
MyMenuListener. The macro program must also construct ASTs representing 
the inserted methods and modify the original large AST to include these ASTs. 
Manipulating a large AST is another difficult task. To reduce these difficulties, 
macro systems should provide logical and contextual information of programs 
for macro programs. There are only a few macro systems providing the logical 
information. For example, XL[15] is one of those systems although it is for a 
functional language but not for an 00 language. 

3 OpenJava 

Open Java is our advanced macro system for Java. In OpenJava, macro programs 
can access the data structures representing a logical structure of the programs. 
We call these data structure class metaobjects. This section presents the design 
of OpenJava 

3.1 Macro Programming in OpenJava 

OpenJava produces an object representing a logical structure of class definition 
for each class in the source code. This object is called a class metaobject. A class 



metaobject also manages macro expansion related to the class it represents. Pro- 
grammers customize the definition of the class metaobjects for describing macro 
expansion. We call the class for the class metaobject metaclass. In OpenJava, 
the metaprogram of a macro is described as a metaclass^ Macro expansion by 
OpenJava is divided into two: the first one is macro expansion of class decla- 
rations (callee-side), and the second one is that of expressions accessing classes 
(caller-side). 

Applying Macros Fig. 1 shows a sample using a macro in OpenJava. By 
adding a clause instantiates M in just after the class name in a class declara- 
tion, the programmer can specify that the class metaobject for the class is an 
instance of the metaclass M. In this sample program, the class metaobject for 
MyMenuListener is an instance of ObserverClass. This metaobject controls macro 
expansion involved with MyMenuListener. The declaration of ObserverClass is 
described in regular Java as shown in Fig. 2. 

class MyMenuListener 

instantiates ObserverClass 

extends MyObject 

implements MenuListener 
< .... > 



Fig. 1. Application of a macro in OpenJava 



class ObserverClass 
extends OJClass 

{ 

void translateDef initionO { . . . > 

} 



Fig. 2. A macro in OpenJava 

Every metaclass must inherit from the metaclass OJClass, which is a built-in 
class of OpenJava. The translateDef initionO in Fig. 2 is a method inherited 
from OJClass, which is invoked by the system to make macro expansion. If an 
instantiates clause in a class declaration is found, OpenJava creates an in- 
stance of the metaclass indicated by that instantiates clause, and assigns this 
instance to the class metaobject representing that declared class. Then Open- 
Java invokes translateDef initionO on the created class metaobject for macro 
expansion on the class declaration later. 



Since the translateDef initionO declared in OJCIass does not perform 
any translation, a subclass of OJCIass must override this method for the desired 
macro expansion. For example, translateDef initionO can add new member 
methods to the class by calling other member methods in OJCIass. Modifications 
are reflected on the source program at the final stage of the macro processing. 

Describing a Metaprogram The method translateDef initionO imple- 
menting the macro for the Observer pattern in section 2.2 is shown in Fig. 3. 
This metaprogram first obtains ail the member methods (including inherited 
ones) defined in the class by invoking getMethodsO on the class metaobject. 
Then, if a member method declared in interfaces is not implemented in the class, 
it generates a new member method doing nothing and adds it to the class by 
invoking addMethodQ on the class metaobject. 

void translateDef InitionO { 

OJMetnodQ a - this. getHethods( this ) ; 
for (int i - 0; i < m. length; { 

OJModifier modif - o[i] .getModif iaroO; 
if (nodif .islbstractO) { 

OJMethod n - new OJMethodCthis, 

mUl .getKodif iersO .removaAbstract () , 
oti] .getReturnTypeO , a[i] .getHaaeO , 
b [i] . getParaoetertypes () , 
nti] . getExceptionTypes 0 , 
makaStatementList ( "return ; " ) ) ; 
this.addKethodCn) ; 

> 

> 

> 



Fig. 3. translateDef initionO in ObserverClass 

As a class is represented by a class metaobjects, a member method is also 
represented by a method metaobjects. In OpenJava, classes, member methods, 
member fields, and constructors are represented by instances of the class OJCIass, 
OJMethod, 0 J Field, and 0 J Constructor, respectively. These metaobject represent 
logical structures of class and member definitions. They are easy to handle, 
compared to directly handling large ASTs representing class declarations and 
collecting information scattered in these ASTs. 

3.2 Class Metaobjects 

As shown in section 2, a problem of ordinary macro systems is that their pri- 
mary data structure is ASTs (abstract syntax trees) but they are far from logical 
sturctures of programs in 00 languages. In 00 languages like Java, class def- 
initions play an important role as a logical structure of programs. Therefore, 
OpenJava employs the class metaobjects model, which was originally developed 
for reflective computing, for representing a logical structure of a program. The 



class metaobjects make it easy for meta programs to access a logical structure 
of program. 

Hiding Syntactical Information In Java, programmers can use various syn- 
tax for describing the logically same thing. These syntactical differences are 
absorbed by the metaobjects. For instance, there are two notations for declaring 
a String array member field: 

String □ a; 
String bQ ; 

Both a and b are String array fields. It would be awkward to write a metapro- 
gram if the syntactical differences of the two member fields had to be considerd. 
Thus OJField provides only two member methods getTypeO and setTypeO 
for handling the type of a member field. getTypeO on the OJField metaobjects 
representing a and b returns a class metaobject representing the array type of 
the class String. 

Additionally, some elements in the grammer represent the same element in 
a logical structure of the language. If one of these element is edited, the others 
are also edited. For instance, the member method setNameQ in OJCIass for 
modifying the name of the class changes not only the class name after the class 
keyword in the class declaration but also changes the name of the constructors. 

Logically Structured Class Representation Simple ASTs, even arranged 
and abstracted well, cannot properly represent a logical structure of a class 
definition. The data structure must be carefully designed to corresponded not 
only to the grammer of the language but also to the logical constructs of the 
language like classes and member methods. Especially, it makes it easy to handle 
the logical information of program including association between names and 
types. 

For instance, the member method ge t Methods () in OJCIass returns all the 
member methods defined in the class which are not only the methods immedi- 
ately declared in the class but also the inherited methods. The class metaobjects 
contain type information so that the definition of the super class can be acces- 
sible. 

3.3 Class Metaobjects in Details 

The root class for class metaobjects is OJCIass. The member methods of OJCIass 
for obtaining information about a class are shown in Tab. 1 and Tab. 2. They 
cover all the attributes of the class. In OpenJava, all the types, including array 
types and primitive types like int, have corresponding class metaobjects. Using 
the member methods shown in Tab. 1, metaprogramms can inspect whether a 
given type is an ordinary class or not. 

Tab. 3 gives methods for modifying the definition of the class. Metaprograms 
can override translateDef initionQ in OJCIass so that it calls these methods 



for executing desired modifications. For instance, the example shown in Fig. 3 
adds newly generated member methods to the class with addMethodO . 



Table 1. Member Methods in OJCIass for Non-Class Types 



boolean islnterfac©() 

Tests if this represents an interface type. 

boolean isArrayO 

Tests if this represents an array type, 
boolean IsPriaitivaC) 

Tests if this represents an premitive type. 

OJCIass go t Component Typ«0 

Returns a class metaobject for the type of array components. 



Metaobjects Obtained through Class Metaobjects The method getSuperclassO 
in OJCIass, which is used to obtain the superclass of the class, returns a class 
metaobject instead of the class name (as a string). As the result, metaprogram 
can use the returned class metaobject to directly obtain information about the 
superclass. OpenJava automatically generates class metaobjects on demand, 
even for classes declared in another source file or for classes available only in 
the form of bytecode, that is, classes whose source code is not available. 

The returned value of the member method getModif iers() in Tab. 2 is an 
instance of the class 0 J Modifier. This class represents a set of class modifiers 
such as public, abstract or final. Metaprogramms do not have to care about 
the order of class modifiers because 0 J Modifier hides such useless information. 

The class OJMethod, which is the return type of getDeclaredMethods () 
in OJCIass, represents a logical structure of a method. Thus, similarly to the 
class OJCIass, this class has member methods for examining or modifying the 
attributes of the method. Some basic member methods in OJMethod are shown in 
Tab. 4. Any type information obtained from these methods is also represented by 
a class metaobject. For instance, getReturnTypeO returns a class, metaobject 
as the return type of the method. This feature of OJMethod is also found in 
0 J Field and 0 J Constructor, which respectively represent a member field and a 
constructor. 

The class StatementList, which is the return type of the member method 
getBodyO in the class OJMethod, represents the statements in a method body. 
An instance of StatementList consists of objects representing either expressions 
or statements. StatementList objects are AST-like data structures although they 
contain type information. This is because we thought that the logical structure 
of statements and expressions in Java can be well represented with ASTs. 



Table 2. Member Methods in OJClass for introspection (1) 



String getPackageNaaaO 

Returns the package name this class belongs to. 
String getSimpleHameO 

Returns the unqualified name of this class. 
OJHodif ier getModif iarsO 

Returns the modifiers for this class. 
OJClass go tSupor class 0 

Returns the superclass declared explicitly or implicitly. 

OJClass □ getDeclaredlnterfacesO 

Returns all the declared superinterfiaces. 

StatementList getlnitializarO 

Returns all the static initializer statements. 
OJFieldQ getDeclaredFieldsO 

Returns ail the declared fields. 
OJKetfcodD getDeclaredHethodsC) 

Returns all the declared methods. 
OJConctructorD getOeclaredCaastructorsO 

Returns all the constructors declared explicitly or implicitly. 

OJClass □ getDeclaredClassesO 

Returns all the member classes (inner classes). 

OJClass getDeclaringClassO 

Returns the class declaring this class (outer class). 



Tkble 3. Member Methods in OJClass for modifying the class 



String setSioplename (String name) 

Sets the unqualified name of this class. 

OJModifier setHodifiers(OJModifier modifs) 
Sets the class modifiers. 

OJClass setSuperclaas (OJClass clazz) 
Sets the superclass. 

OJClass □ set Interfaces (OJClass D faces) 
Sets the superinterfaces to be declared. 

OJField removeField(OJField field) 

Removes the given field from this class declaration. 

OJKethod removeHethod(OJMethod method) 

Removes the given method from this class declaration. 

OJConstnictor raaoveCanstructor (OJConstnictor canstr) 

Removes the given constructor from this class declaration. 

OJField addField (OJField field) 

Adds the given field to this class declaration. 

OJHathod addMethod (0 JHathod method) 

Adds the given method to this class declaration. 

OJConstnictor addConstractor (OJConstnictor coastr) 
Adds the given constructor to this class declaration. 



Table 4. Basic Methods in OJMethod 



String getKamaO 

Returns the name of this method. 
OJHodifier getModif iersO 

Returns the modifiers for this method. 
DJClass getttaturnTypaO 

Returns the return type. 

OJClass □ getParaeterTypesO 

Returns the parameter types in declaration order. 
OJClass □ getErceptionTypesO 

Returns the types of the exceptions declared to be thrown. 
StriagQ getParaaeterVariablesO 

Returns the parameter variable names in declaration order. 
StatenaatList get Body () 

Returns the statements of the method body. 
String s at Nana (String name) 

Sets the name of this method. 

OJModifier rotModiliersCOJHodifier nodifs) 

Sets the method modifiers. 
OJClass eetRetnrnTypoO 

Sets the return type. 

OJClass D setParaneterTypesO 

Sets the parameter types in declaration order. 
OJClass □ setExceptionTypeaO 

Sets the types of the exceptions declared to be thrown. 
String C] setParaaeterVariablesO 

Sets the parameter variable names in declaration order. 
StatementList setBodyO 

Sets the statements of the method body. 



Logical Structure of a Class Tab. 5 shows the member methods in 0 JCIass 
handling a logical structure of a class. Using these methods, metaprograms can 
obtain information considering class inheritance and member hiding Although 
these ^member methods can be implemented by combining the member methods 
in iab.2, they are provided for convenience. We think that providing these meth- 
ods is significant from the viewpoint that class metaobjects represent a logical 
structure of a program. 

Table 5. Member Methods in 0 JCIass for introspection (2) 



OJClaseO getlnterfacesO 

Returns all the interfaces implemented by this class or the all the super- 
interfaces of this interface. 

boolean i aAssignableFroa (0 JCIass clazz) 

Determines if this class/ interface is either the same as, or is a superclass 
or superinterface of, the given class/interface. 

OJHethodD getKothods (OJClass situation) 

Returns all the class available from the given situation, including those 
declared and those inherited from superclasses /superinterf aces . 

OJMettod getltethodCString name, 0 JCIass 0 types, OJClass situation) 
Returns the specified method available from the given situation. 

OJJtethod getlavokedMethodtString nana, D JCIass □ types, OJClass situation) 
Returns the method, of the given name, invoked by the given arguments 
types, and available from the given situation. 



In considering the class inheritance mechanism, the member methods de- 
fined in a given class are not only the member methods described in that class 
declaration but also the inherited ones. Thus, method metaobjects obtained by 
invoking getMethods () on a class metaobject include the methods explicitly de- 
clared in its class declaration but also the methods inherited from its superclass 
or superinterfaces. 

Moreover, accessibility of class members is restricted in Java by member 
modifiers like public, protected or private. Thus, getMethods () returns 
only the member methods available from the class specified by the argument. 
For instance, if the specified class is not a subclass or in the same package, 
getMethods () returns only the member methods with public modifier. In Fig. 3, 
since the metaprogram passes this to getMethods (), it obtains all the member 
methods defined in that class. 

3.4 Type-Driven Translation 

As macro expansion in OpenJava is managed by metaobjects corressponding to 
each class (type), this translation is said to be type-driven. In the above example, 
only the member method translateDef initionO of OJClass is overridden to 
translate the class declarations of specified classes (callee-side translation). 



In addition to the callee-side translation, OJClass provides a framework to 
translate the code related to the corresponding class spreaded over whole pro- 
gram selectively (caller-side translation). The parts related to a certain class is, 
for example, instance creation expressions or field access expressions. 

Here, we take up an example of a macro that enables programming with 
the Flyweight[6] pattern to explain this mechanism. This design pattern is 
applied to use objects-sharing to support large numbers of fine-grained objects 
efficiently. An example of macro supporting uses of this pattern would need to 
translate an instance creation expression of a class Glyph: 

new Glyph('c') 

into a class method call expression: 

GlyphFactory . createCharact er ( ' c ' ) 

The class method createCharacter O returns an object of Glyph correspon- 
dent to the given argument if it was already generated, otherwise it creates a new 
object to return. This way, the program using Glyph objects automatically shares 
an object of Glyph representing a font for a letter c without generating several ob- 
jects for the same letter. In ordinary programming using Glyph objects with the 
Flyweight pattern, programmers must explicitly write createCharacter () in 
their program with creations of Glyph objects. With a support of this macro, 
instance creations can be written in the regular new syntax and the pattern is 
used automatically. 

In OpenJava, this kind of macro expansions are implemented by defining a 
metaclass FlyweightClass to be applied to the class Glyph. This metaclass over- 
rides the member method expandAllocationO of OJClass as in Fig.4. This 
method receives a class instance creation expression and returns a translated 
expression. The system of OpenJava examines the whole source code and apply 
this member method to each Glyph instance creation expression to perform the 
macro expansion. 

Expression axpanrUI 1 neat ion (AIlocationExpression expr, Environment env) { 
Express ionLiet args - expr . get Arguments ( ) ; 
return new KetnodCallCthls, "createCharacter" , args); 

> 

Fig. 4. Replacement of class instance expressions 

The member method expandAllocationO receives an Allocation Expression 
object representing a class instance creation expression and an Environment ob- 
ject representing the enviroment of this expression. The Environment object holds 
name binding information such as type of variable in the scope of this expression. 

OpenJava uses type-driven translation to enable the complehensive macro 
expansion of partial code spreaded over various places in program. In macro 
systems for 00 programing languages, it is not only needed to translate a class 



£d£ n n ¥ b u *ST tiDg eXpressions ^ *• cla^s togather is also 
needed, In OpenJava, by defining a methods like expandAllocationO metapT 
grammers can selectively apply macro expansion to the limited expressions £ 
lated to classes controlled by the metaclass. This kind of mechanism Jet 
seen m most of ordinary macro systems except some systems like OpenC++[31 
Tab. 6 shows the primary member methods of OJCIass which can be overridden 
for macro expansion at caller-side. ™ 

Table 6. Member Methods for Each Place Applied the Macro-Expansion to 



Member method 
transUt«Daf iaitlanO 



upandillocatianO 
oxpandArrayUlocat ion () 
«xpaadXypeHameO 
«xpandHethodCall() 
expaadFieldRead () 
«zpandFieldUrit« () 
oxpandCastadSzpressionC) 
•xpandCagtBrpressian ( ) 



f lace appli ed the macro expansion to" 

Class declaration 

Class instance allocation expression 
Array allocation expression 
Class name 

Method class expression 
Field-read expression 
Fie Id- write expression 
Casted expression from this type 
Casted expression to this type 



3.5 Translation Mechanism 

Given a source program, the processor of OpenJava: 

1. Analyzes the source program to generate a class metaobject for each 
class. 

2. Invokes the member methods of class metaobjects to perform macro 
expansion. 

3. Generates the regular Java source program reflecting the modifica- 
tion made by the class metaobjects. 

4. Executes the regular Java compiler to generate the corresponding 
byte code. 

The Order of Translations Those methods of OJCIass whose name start from 
expand performs caller-side translation, and they affect expressions in source 
program declaring another class C. Such expressions may also be translated by 
translateDef initionO of the class metaobject of C as callee-side translation. 
Thus different class metaobjects affect the same part of source program. 

In OpenJava, to resolve this ambiguousness of several macro expansion, 
the system always invokes translateDef initionO first as callee-side transla- 
tion, then it apply caller-side translation to source code of class declarations 
which was already applied callee-side translation. Metaprogrammers can de- 
sign metaprogram considering this specified order of translation. In this rule, 



if translateDef initionO changes an instance creation expression of class X 
into Y's, expandAllocationO defined in the metaclass of X is not performed. 

Moreover, the OpenJava system always performs translateDef initionO 
for superclasses first, i.e. the system performs it for subclasses after superclasses. 
As a class definition strongly depends on the definition of its superclass, the 
translation of a class often varies depending on the definition of its superclass. 
To settle the definition of superclasses, the system first translates the source 
program declaring superclasses. Additionally, there are some cases where the 
definition of a class D affects the result of translation of a class E. In Open- 
Java, from translateDef initionO for E, metaprogrammer can explicitly spec- 
ify that translateDef initionO for D must be performed before. 

In the case there are dependency relationships of translation among several 
macro expansions, consistent order of translation is specified to address this 
ambiguousness of translation results. 

Dealing with Separate Compilation In Java, classes can be used in program 
only if they exist as source code or byte code (.class file). If there is no source 
code for a class C, the system cannot specifiy the metaclass of C, as is. Then, for 
instance, it cannot perform the appropriate expandAllocationO on instance 
creation expressions of C. 

Therefore, OpenJava automatically preserves metalevel information such as 
the metaclass name for a class when it processes the callee-side translation of each 
class. These preservation are implemented by translating these information into a 
string held in a field of a special class, which is to be compiled into byte code. The 
system uses this byte code to obtain necessary metalevel information in another 
process without source code of that class. Additionally, metaprogrammers can 
request the system to preserve customized metalevel information of a class. 

Metalevel information can be preserved as special attributes of byte code. 
In OpenJava, such information is used only at compile-time but not at runtime. 
Thus, in order to save runtime overhead, we choosed to preserve such information 
in separated byte code which is not to be loaded by JVM at runtime. 

3.6 Syntax Extension 

With OpenJava macros, a metaclass can introduce new class/member modifiers 
and clauses starting with the special word at some limited positions of the regular 
Java grammar. The newly introduced clauses are valid only in the parts related 
to instances of the metaclass. 

In a class declaration (callee-side), the positions allowed to introduce new 
clauses are: 

- before the block of member declarations, 

- before the block of method body in each method declaration, 

- after the field variable in each field declaration. 



And in other class declarations (caller-side), the allowed position is: 



— after the name of the class. 

Thanks to the limited positions of new clauses, the system can parse source 
programs without conflicts of extended grammers. Thus, metaprogrammers do 
not have to care about conflicts between clauses. 



class VectorStack instantiates AdaptarClass 
adapts Vector in v to Stack 

< 



Fig. 5. An example of syntax extension in OpenJava 

Fig. 5 shows an example source program using a macro, a metaclass Adapter- 
Class, supporting prograinming with the Adapter pattern[6J. The metaclass in- 
troduces a special clause beginning with adapts to make programmers to write 
special description for the Adapter pattern in the class declaration. The adapts 
clause in the Pig. reffigrVectorStack VectorStack is the adapter to a class Stack 
for a class Vector. The information by this clause is used only when the class 
metaobjects representing VectorStack performs macro expansion . Thus, for other 
class metaobjects, semantical information added by the new clause is recognized 
as a regular Java source code. 

static SyntaxRule getDeclSuf fix (String keyword) { 
if (keyword. equals ("adapts")) { 
return new Compositeftule( 
new TypeHaaaftoleO, 

new PrepPnraseRule("in\ new IdentifierRuleO) , 
^ new PrepPhraseftoleCto-, new TypeBaneRnleO) ); 

return null; 

> 

Fig. 6. A meta-program for a customized suffix 

To introduce this adapts clause, metaprogrammers implement a member 
method getDeclSuff ix() in the metaclass AdapterClass as shown in Fig. 6. 
The member method getDeclSuf f ix() is invoked by the system when needed, 
and returns a SyntaxRule object representing the syntax grammer begenning 
with the given special word. An instance of the class SyntaxRule implements 
a recursive descendant parser of LL(k), and analyzes a given token series to 
generate an appropriate AST. The system uses SyntaxRule objects obtained by 
invoking getDeclSuf fix () to complete the parsing. 

For meUprogrammers of such SyntaxRule objects, OpenJava provides a class 
library of subclasses of SyntaxRule, such as parsers of regular Java syntax ele- 
ments and synthesizing parser for tying, repeating or selecting other SyntaxRule 



objects. Metaprogrammers can define their desired clauses by using this library 
or by implementing a new subclass of SyntaxRule. V 

3.7 Metaclass Model of OpenJava 

A class must be managed by a single metaclass in OpenJava. Though it would 
be useful rf programmers could apply several metaclasses to a class we did not 
implement such a feature because there is a problem of conflict of translation 
between metaclasses. And, a metaclass for a class A does not manage a subclass 
A of A, that is, the metaclass of A does not perform the callee-side and caller- 
side translation of A' it is not specified to be the metaclass of A' in the source 
program declaring A'. 

For innerclasses such as member classes, local classes, anonymous classes in 
the Java language, each of them are also an instance of a metaclass in OpenJava 
lims programmers may apply a desired metaclass to such classes. 

4 Related Work 

There are a number of systems using the class metaobjects model for represents 
m^i2 IUCt ] IIe ° f a P n « ram: S-KRS[iq f 0bjVlisp[5], CLOS M0P[13J, 
Smalltalk-80[8], and so on. The reflection APIfll] of the Java language also uses 
this model although the reflection API does not allow to change class metaob- 
jects; it only allows to inspect them. Furthermore, the reflection API uses class 
metaobjects for making class definition accessible at runtime. On the other hand, 
OpenJava uses class metaobjects for macro expansion at compile-time. 

0penC++[3] also uses the class metaobject model OpenJava inherits sev- 
eral features, such as the type-driven translation mechanism, from OpenC-f +. 
However, the data structure mainly used in OpenC-H- is still an AST (abstract 
syntax tree). MPC++[10] and EPP[9] are similar to OpenC++ with respect to 
the data structure. As mentioned in section 2, an AST is not an appropriate 
abstraction for some macros frequently used in 00 programming. 

5 Conclusion 

This paper describes OpenJava, which is a macro system for Java providing 
a data structure called class metaobjects. A number of research activities have 
been done for enhancing expressive power of macro systems. This research is also 
in this stream. OpenJava is a macro system with a data structure representing 
a logical structure of an 00 program. This made it easier to describe typical 
macros for 00 programming which was difficult to describe with ordinary macro 
systems. 

To show the effectiveness of OpenJava, we implemented some macros in 
OpenJava for supporting programming with design patterns. Although we saw 
that class metaobjects are useful for describing those macros, we also found 



limitations of OpenJava. Since a single design pattern usually contains several 

^Ui T 010 SySt6m 8houId be able to deal ™ th those Masses as a single 
entity[17]. However it is not easy for OpenJava to do that because macros are 
applied to each class. It is future work to address this problem by incorporate 
OpenJava with techniques like aspect^oriented prograinniing[12]. 
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Preface 



The Java™ Media Framework (JMF) is an application programming inter- 
face (API) for incorporating time-based media into Java applications and 
applets. This guide is intended for Java programmers who want to incor- 
porate time-based media into their applications and for technology pro- 
viders who are interested in extending JMF and providing JMF plug-ins to 
support additional media types and perform custom processing and ren- 
dering. 



About JMF 

The JMF 1.0 API (the Java Media Player API) enabled programmers to 
develop Java programs that presented time-based media. The JMF 2.0 API 
extends the framework to provide support for capturing and storing 
media data, controlling the type of processing that is performed during 
playback, and performing custom processing on media data streams. In 
addition, JMF 2.0 defines a plug-in API that enables advanced developers 
and technology providers to more easily customize and extend JMF func- 
tionality. 

The following classes and interfaces are new in JMF 2.0: 



Audio Format 

BufferControl 

CaptureDevi ce 

CI oneabl eDa taSou rce 

ConnnecrionErrorEvent 

DataSi nkEvent 



BitRateControl 

BufferToImage 

Captu reDevi ceinf o 

Codec 

DataSink 

DataSi nkListener 



Buffer 

BufferTransferHandler 
Captu reDevi ceManager 
Conf i gureCompl eteEvent 
DataSi nkErrorEvent 
Demultipl exer 
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Effect 


EndOfStreamEvent 


Fi 1 eTy peDescri pto r 


Format 


FormatChangeEvent 


Format Control 


FrameCrabbi ngControl 


FramePosi ti oni ngCont rol 


FrameProcessi ngControl 


FrameRateControl 


H261Control 


H2 61 Format 


H263Control 


H263Format 


ImageToBuffer 


IndexedCol orForraat 


InputSourceStream 


KeyFrameControl 


MonitorControl 


MpegAudioControl 


Multiplexer 


NoStorageSpaceErrorEvent 


PacketSizeControl 


Plugln 


PluglnManager 


PortControl 


Processor 


ProcessorModel 


Pul 1 Buff erDataSou rce 


Pull Buff erStream 


PushBufferDataSource 


PushBufferStream 


QualityControl 


Renderer 


RCBFormat 


Si 1 enceSuppressi onCont rol 


StrearaWri terControl 


Track 


TrackControl 


VideoFormat 


Vi deoRenderer 


YUVFormat 



In addition, the Medi aPl ayer Java Bean has been included with the JMF 
API in j avax . medi a . bean . pi ayerbean. Medi aPl aye r can be instantiated 
directly and used to present one or more media streams. 

Future versions of the JMF API will provide additional functionality and 
enhancements while maintaining compatibility with the current APL 

Design Goals for the JMF API 

JMF 2.0 supports media capture and addresses the needs of application 
developers who want additional control over media processing and ren- 
dering. It also provides a plug-in architecture that provides direct access 
to media data and enables JMF to be more easily customized and 
extended. JMF 20 is designed to: 

• Be easy to program 

• Support capturing media data 

• Enable the development of media streaming and conferencing 
applications in Java 



• Enable advanced developers and technology providers to implement 
custom solutions based on the existing API and easily integrate new 
features with the existing framework 

• Provide access to raw media data 

• Enable the development of custom, downloadable demultiplexers, 
codecs, effects processors, multiplexers, and Tenderers (JMF plug-ins) 

• Maintain compatibility with JMF 1.0 



About the JMF RTP APIs 

The classes in j avax . medi a . rtp , j avax . medi a . rtp . event, and 
javax . medi a. rtp. rtcp provide support for RIP (Real-Time Transport Pro- 
tocol). RTP enables the transmission and reception of real-time media 
streams across the network. RTP can be used for media-on-demand appli- 
cations as well as interactive services such as Internet telephony. 

JMF-compliant implementations are not required to support the RTP 
APIs in javax. media. rtp, javax. media. rtp. event, and 
javax . medi a . rtp . rtcp. The reference implementations of JMF provided 
by Sun Microsystems, Inc. and IBM Corporation fully support these APIs. 

The first version of the JMF RTP APIs (referred to as the RTP Session Man- 
ager API) enabled developers to receive RTP streams and play them using 
JMF. Li JMF 2.0, the RTP APIs also support the transmission of RTP 
streams. 

The following RTP classes and interfaces are new in JMF 2.0: 

SendStream SendStreamLi stener Inacti veSendStreamEvent 

ActiveSendStreamEvent SendPayl oadChangeEvent NewSendStreamEvent 

GlobalTransmissionStats Transmi ssi onStats 

The RTP packages have been reorganized and some classes, interfaces, 
and methods have been renamed to make the API easier to use. The pack- 
age reorganization consists of the following changes: 

• The RTP event classes that were in javax. media, rtp. session arenow 
in j avax . medi a . rtp . event. 

• The RTCP-related classes that were in javax. media, rtp. session are 
now in javax . medi a . rtp . rtcp. 
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The rest of the classes in j avax . medi a . rtp . ses si on are now in 
javax. media, rtp and the javax. media, rtp. session package has been 
removed. 



The name changes consist primarily of the removal of the RTP and RTCP 
prefixes from class and interface names and die elimination of non-stan- 
dard abbreviations. For example, RTPRecvStreamListener has been 
renamed to ReceiveStreamListener. For a complete list of the changes 
made to the RTP packages, see the JMF 2.0 Beta release notes. 

In addition, changes were made to the RTP APIs to make them compatible 
with other changes in JMF 2.0: 

• javax. media. rtp. session. io and 

javax . medi a. rtp . sessi on . depacketi zer have been removed. Custom 
RTP packetizers and depacketizers are now supported through the 
JMF 2.0 plug-in architecture. Existing depacketizers will need to be 
ported to the new plug-in architecture. 

• Buffer is now the basic unit of transfer between the Sessi onManager 
and other JMF objects, in place of DePacketi zedUni t and 
DePacketizedObject. RTP-formatted Buffers have a specific format 
for their data and header objects. 

• BaseEncodi nglnf o has been replaced by the generic JMF Format object. 
An RTP-specific Format is differentiated from other formats by its 
encoding string. Encoding strings for RTP-specific Formats end in 
_RTP. Dynamic payload information can be provided by associating a 
dynamic payload number with a Format object. 

Design Goals for the JMF RTP APIs 

The RTP APIs in JMF 2.0 support the reception and transmission of RTP 
streams and address the needs of application developers who want to use 
RTP to implement media streaming and conferencing applications. These 
APIs are designed to: 

• Enable the development of media streaming and conferencing 
applications in Java 

• Support media data reception and transmission using RTP and RTCP 

• Support custom packetizer and depacketizer plug-ins through the 
JMF 2.0 plug-in architecture. 

• Be easy to program 
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Partners in the Development of the JMF API 

The JMF 2.0 API is being jointly designed by Sun Microsystems, Inc. and 
IBM Corporation. 

The JMF 1.0 API was jointly developed by Sun Microsystems Inc., Intel 
Corporation, and Silicon Graphics, Lie. 

Contact Information 

For the latest information about JMF, visit the Sun Microsystems, Inc. 
website at: 

http : //j ava . sun . com/products/ java-medi a/ jmf / 

Additional information about JMF can be found on the IBM Corporation 
website at: 

http : //www . software . i bra . com/net . roedi a/ 



About this Document 

This document describes the architecture and use of the JMF 2.0 API. It 
replaces the Java Media Player Guide distributed in conjunction with the 
JMF 1.0 releases. 

Except where noted, the information in this book is not implementation 
specific. For examples specific to the JMF reference implementation devel- 
oped by Sun Microsystems and IBM corporation, see the sample code and 
solutions available from Sun's JMF website (http://java. sun . com/prod- 
ucts/java-medi a/jmf/i ndex. html ). 

Guide to Contents 

This document is split into two parts: 

• Part 1 describes the features provided by the JMF 2.0 API and 
illustrates how you can use JMF to incorporate time-based media in 
your Java applications and applets. 

• Part 2 describes the support for real-time streaming provided by the 
JMF RTP APIs and illustrates how to send and receive streaming 
media across the network. 
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Part 1 is organized into six chapters: 

• "Working with Time-Based Media"-sets the stage for JMF by 
introducing the key concepts of media content, presentation, 
processing, and recording. 

• "Understanding JMF'-introduces the JMF 2.0 API and describes the 
high-level architecture of the framework. 

• 7^ SentinS Time-Based Media with JMF'-describes how to use 
JMF Players and Processors to present time-based media. 

• "Processing Time-Based Media with JMF"— describes how to 
manipulate media data using a JMF Processor. 

• "Capturing Time-Based Media with JMF'-desaibes how to record 
media data using JMF DataSources and Processors. 

• "Extending JMF" — describes how to enhance JMF functionality by 
creating new processing plug-ins and implementing custom JMF 
classes. 

Part 2 is organized into six chapters: 

• ^orkmgwithReal-TimeMediaStreams^-providesanoverviewof 
streaming media and the Real-time Transport protocol (RTP). 

• "Understanding the JMF RTP API"— describes the JMF RTP APIs. 

• "Receiving and Presenting RTP Media Streams"— illustrates how to 
handle RTP Client operations. 

• "Transmitting RTP Media Streams"— illustrates how to handle RTP 
Server operations. 

• "Importing and Exporting RTP Media Streams"— shows how to read 
and write RTP data to a file. 

• "Creating Custom Packetizers and Depacketizers"— describes how 
to use JMF plug-ins to support additional RTP packet formats and 
codecs. 

At the end of this document, you'll find Appendices that contain complete 
sample code for some of the examples used in these chapters and a glos- 
sary of JMF-specific terms. & 
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Change History 

Version JMF 2.0 FCS 

• Fixed references to TrackControl methods to reflect modified 
TrackControl API. 

• Fixed minor sample code errors. 

• Clarified behavior of cloneable data sources. 

• Clarified order of events when writing to a file. 
Version 0.9 

Internal Review Draft 

Version 0.8 

JMF 2.0 Beta draft: 

• Added an introduction to RTP, Working with Real-Time Media 
Streams, and updated the RTP chapters. 

• Updated to reflect API changes since the Early Access release. 

• Added an example of registering a plug-in with the PI uglnManager. 

• Added chapter, figure, table, and example numbers and changed the 
example code style. 

Version 0.7 

JMF 2.0 Early Access Release 1 draft: 

• Updated and expanded RTP chapters in Part 2. 

• Added Demultiplexer example to "Extending JMF". 

• Updated to reflect API changes since the public review. 
Version 0.6 

Internal Review Draft 
Version 0.5 

JMF 2.0 API public review draft. 

• Added new concepts chapter, "Working with Time-Based Media". 

• Reorganized architecture information in 'Understanding JMF". 
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JMF 2.0 API licensee review draft. 
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Working with 
Time-Based Media 



Any data that changes meaningfully with respect to time can be character- 
ized as time-based media. Audio clips, MIDI sequences, movie clips, and 
animations are common forms of time-based media. Such media data can 
be obtained from a variety of sources, such as local or network files, cam- 
eras, microphones, and live broadcasts. 

This chapter describes the key characteristics of time-based media and 
describes the use of time-based media in terms of a fundamental data pro- 
cessing model: 






Process 

MM Apply effect filters 
Read from a file a «-»A Compress or decompress 



Output 



Receive from 
the network 



A * B Convert between formate 



Present 



Save to a file 



Send across 
the network 



Figure 1-1: Media processing model. 
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Streaming Media 

A key characteristic of time-based media is that it requires timely delivery 
and processing. Once the flow of media data begins, there are strict riming 
deadlines that must be met, both in terms of receiving and presenting the 
data. For this reason, time-based media is often referred to as streaming 
media— it is delivered in a steady stream that must be received and pro- 
cessed within a particular timeframe to produce acceptable results. 

For example, when a movie is played, if the media data cannot be deliv- 
ered quickly enough, there might be odd pauses and delays in playback. 
On the other hand, if the data cannot be received and processed quickly 
enough, the movie migfrt appear jumpy as data is lost or frames are inten- 
tionally dropped in an attempt to maintain the proper playback rate. 



Content Type 

The format in which the media data is stored is referred to as its content 
type. QuickTime, MPEG, and WAV are all examples of content types. Con- 
tent type is essentially synonymous with file type— content type is used 
because media data is often acquired from sources other than local files. 



Media Streams 

A media stream is the media data obtained from a local file, acquired over 
the network, or captured from a camera or microphone. Media streams 
often contain multiple channels of data called tracks. For example, a 
Quicktime file might contain both an audio track and a video track. Media 
streams that contain multiple tracks are often referred to as multiplexed or 
complex media streams. Demultiplexing is the process of extracting individ- 
ual tracks from a complex media stream. 

A track's type identifies the kind of data it contains, such as audio or 
video. The format of a track defines how the data for the track is struc- 
tured. 

A media stream can be identified by its location and the protocol used to 
access it. For example, a URL might be used to describe the location of a 
QuickTime file on a local or remote system. If the file is local, it can be 
accessed through the FILE protocol. On the other hand, if it's on a web 
server, the file can be accessed through the HTTP protocol. A media locator 
provides a way to identify the location of a media stream when a URL 
can't be used. 
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Media streams can be categorized according to how the data is delivered: 

• PulWata transfer is initiated and controlled from the client side For 
example, Hypertext Transfer Protocol (HTTP) and FILE are pull ' 
protocols. F 

• Push-the server initiates data transfer and controls the flow of data 
For example, Real-time Transport Protocol (RTP) is a push protocol ' 
used for streaming media. Similarly, the SGI MediaB4 protocol is a 
push protocol used for video-on-demand (VOD). 

Common Media Formats 

The f oUowmg tables identify some of the characteristics of common media 
formate. When selecting a format, if s important to take into account the 
Aaractensbcs of the format, the target environment, and the expectations 
of the intended audience. For example, if you're delivering media content 
via the web, you need to pay special attention to the bandwidth require- 
ments. ^ 

The CPU Requirements column characterizes the processing power neces- 
sary for optimal presentation of the specified format The Bandwidth 
Requirements column characterizes the transmission speeds necessary to 
send or receive data quickly enough for optimal presentation. 

Format Content Type Quality CPU Bandwidth 
Requirements Requirements 



Cinepak 


AVI 

QuickTime 


Medium 


Low 


High 


MPEG-1 


MPEG 


High 


High 


High 


H.261 


AVI 
RTP 


Low 


Medium 


Medium 


H.263 


QuickTime 

AVI 

RTP 


Medium 


Medium 


Low 


JPEG 


QuickTime 

AVI 

RTP 


High 


High 


High 
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Format Content Type Quality 



Indeo 

Table 1-1: Common video formats. 



QuickTime Medium 
AVI 



CPU Bandwidth 
Requirements Requirements 

Medium Medium 



Format 


content type 


Quality 


CPU 
Requirements 


Bandwidth 
Requirements 




AVI 

QuickTime 
WAV 


High 


Low 


High 


Mu-Law 


AVI 

QuickTime 

WAV 

RTP 


Low 


Low 


High 


ADPCM 

(DVI, 

IMA4) 


AVI 

QuickTime 

WAV 

RTP 


Medium 


Medium 


Medium 


MPEG-1 


MPEG 


High 


High 


High 


MPEG 
Layer3 


MPEG 


High 


High 


Medium 


GSM 


WAV 
RTP 


Low 


Low 


Low 


G.723.1 


WAV 
RTP 


Medium 


Medium 


Low 



Table 1-2: Common audio formats. 



Some formats are designed with particular applications and requirements 
in mind. High-quality, high-bandwidth formats are generally targeted 
toward CD-ROM or local storage applications. H.261 and H.263 are gener- 
ally used for video conferencing applications and are optimized for video 
where there's not a lot of action. Similarly, G.723 is typically used to pro- 
duce low bit-rate speech for telephony applications. 
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Media Presentation 



Most fane-based media is audio or video data that can be presented 



the most common destmatum for media data output. Media streams can 
dso be sent to other destinations-for exampleZved ^T^TSSft 
ted acroj Ae network. An output destination for media data is so^T 



Presentation Controls 



While a media stream is being presented, VCR-style presentation controls 
Zl h i n PK ;i ded to Cnable *« ^ *> control playback. For e^mX a 
£nt£lpane for a movie player might offer buttorjf or stoppm & 
fast-forwardmg, and rewinding the movie. & 

Latency 

«rt^STl I ^ CUla1 ^ WhCn P^^S a ™dia stream that resides 
on the network, the presentation of die media stream cannot begin imme- 

Zt * ** as a d elay between the time that 

they dick the start button and the time when playback actually starts. 

Multimedia presentations often combine several types of time-based 
^Ltf^ 0 , 3 S >T^ roni2ed Presentation. For example, background music 
might be played during an image slide-show, or animated text might be 
synchronized with an audio or video clip. When the presentation of multi- 
ple media streams is synchronized, it is essential to take into account the 
start latency of each stream-otherwise the playback of the different 
streams might actually begin at different times. 

Presentation Quality 

The quality of the presentation of a media stream depends on several fac- 
tors, including: 

• The compression scheme used 

• The processing capability of the playback system 

• The bandwidth available (for media streams acquired over the 
network) 
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"2^S2^1tr T ter 

To adueve high^uaUty video presentadons, the number of frames dis 
Media Processing 

Sl^SSfT* ^ 3 media stream is manipulated before it " 



IS 

occur 



1. If the stream is multiplexed, the individual tracks are extracted. 

2. If the individual tracks are compressed, they are decoded. 

3. If necessary, me tracks are converted to a different format. 

4. Effect filters are applied to the decoded tracks (if desired). 

The tracks are then delivered to the appropriate output device If the 
mecua stream is to be stored instead of rendered to an oS£*v£f the 
processing stages might differ slightly. For example, if you w^ted [to «L 
toaud.oandvideo^mavideocaLr^ 

1. The audio and video tracks would be captured. 

2. Effect filters would be applied to the raw tracks (if desired). 

3. The individual tracks would be encoded. 

4 ?tr e eam mPreSSed * muW P lexed **> a ^gle media 

5. The multiplexed media stream would then be saved to a file. 
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Demultiplexers and Multiplexers 



A demultiplexer extracts individual tracks of media data from a multi- 
plexed media stream. A mutliplexer performs the oppos teZchonlt 



Codecs 



^ c .media-data compression and decompression When a 

a^tl d - * 18 C P nV6rted fo 3 """pressed format^taUe for stor 
age ortramrmssion; when it is decoded it is converted to a non-com 
pressed (raw) format suitable for presentation. 

wu C . haS C6rtain mput formats iJ can handle and certain outout 
fo^atsmatitcangenerate.msomesitua^aseriesof 
used to convert from one format to another. ^ 

Effect Filters 

An effect filter modifies the track data in some way, often to create special 
effects such as blur or echo. special 

Effect filters are classified as either pre-processing effects or post-process- 
ing effects, depending on whether they are applied before or after ST 

SrT? t e 6ffeCt ffltelS a PP lied to uncom- 

pressed (raw) data. 

Renderers 

A renderer is an abstraction of a presentation device. For audio, the pre- 
sentation device is typically the computer's hardware audio card that out- 
puts sound to the speakers. For video, the presentation device is typically 
the computer monitor. 3V y 

Compositing 

Certain specialized devices support compositing. Compositing time-based 
media is the process of combining multiple tracks of data onto a single 
presentation medium. For example, overlaying text on a video presenta- 
tion is one common form of compositing. Compositing can be done in 

^ a ? Ware or f^f 6 ' A device mat P^ 01 ™ compositing can be 
abstracted as a tenderer that can receive multiple tracks of input data 
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Media Capture 

v,deo«pture card can be used toobtai^vidtfemaZZ Onh 3 
^thoughtofasthe^^phaseofthestandarTmr^^ 8 

A capture device might deliver multiple media streams Forexamnl,. , 
video camera might deliver both audio and video Z 

caphxred and manipulated separately or coSEfiZ. & * 

plexed stream that contains both an audio track and™* de^T 

Capture Devices 

To cap to time-basedmedia you need specialized hardware-f or exam- 
ple, to capture audio from a live source, vou need a mirW^ ? 
appropriate audio card. Similarly, captuing : W ^ 
tuner and an appropriate video capture card. Most system S a 
query mechanism to find out what capture devices are 3fe 

Capture devices can be characterized as either push or pull sources For 

an image. A microphone is a push source-the live source continuoushT 
provides a stream of audio. wnunuousiy 

2^"** 3 "P"*? m6dia Stream on me Processing per- 

formed by the capture device. Some devices do very little processed 
de iver raw, uncompressed data. Other capture devices might deuvfr Te 
data in a compressed format. e 

Capture Controls 

nr^r S ° metimeS P rovided to enable *e user to manage the capture 
process. For example, a capture control panel might enable me user to 

SS^** r enCOdin8 ***** me stream an" start 

and stop the capture process. 
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Java™ Media Framework (JMF) provides a unified architecture and m « 
~ ^u^'J^ iS deSigned to s 4ortmosTstand^media 

SSKXv as AU - AVI - GSM - ^ ^ ^-kC 

£ SnSSSS 6 a * ran ^» e8 ° f me J ava P 1 ***™, JMF delivers the prom- 
ise of -WnteOnce, Run Anywhere™" to developers who want to use 
media such as audio and video in their Java programs. JMF provided 

works. JMF implementations can leverage the capabihties of the underlv- 
mg operating system, while developers can easily create portable Java 
programs that feature time-based media by writing to the JMF API. 

With JMF, you can easily create applets and applications that present, cap- 
ture, manipulate, and store time-based media. The framework enables 
advanced developers and technology providers to perform custom pro- 
cessing of raw media data and seamlessly extend JMF to support addi- 
tional content types and formats, optimize handling of supported formats 
and create new presentation mechanisms. 

High-Level Architecture 

Devices such as tape decks and VCRs provide a familiar model for record- 
ing, processing, and presenting time-based media. When you play a movie 
using a VCR, you provide the media stream to the VCR by insertine a 
video tape. The VCR reads and interprets the data on the tape and sends 
appropriate signals to your television and speakers. 



u 
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Video camera 

(Capture Device) 




Video tape 

(Data Source) 



VCR 

(Player) 




Output Devices 

Figure 2-1: Recording, processing, and presenting time-based media. 

JMF uses this same basic model. A data source encapsulates the media 
steam much kke a video tape and a player provides processed con- 

wS^*™ t0 3 VCR - capt^rmgau^a^dvTdeo 

reqmreS a PP r °Priate input and output devices suchas 
microphones, cameras, speakers, and monitors. 

Data sources and players are integral parts of JMF's high-level API for 
managing the capture, presentation, and processing of time-based media 

nT of 3 l0Wer " leVd *" SU PP 0rte seamlSte^a 
non of custom processing components and extensions. This layeringpro- 
vides Java developers with an easy-to-use API for incorporating^ 
eS^SS? Z a Pr0gramS While niaintaining the r£xibilir> and 

SSSESff to support advanced media « ons - d **« 
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Time Model 

JMF keeps time to nanosecond precision. A particular point in time is tvn- 

s^^tf a Ti me *> me ***** alsoTupport thT 

specification of time in nanoseconds. Fportme 

Classes that support the JMF time model implement CI ock to keep track of 
toeforaparncularmedia stream. The Clock interface definesXba^c 



sentation of media data. 




Clock 


has 




syncStart 






stop 






getMediaTime 






setMediaTiroe 






getRate 






setRate 






getStopTime 






setStopTime 






getTimeBase 






setTimeBase 




Figure 2-3: JMF time model. 



TimeBase 



getTime 

getNanoseconds 



Time 



TimeClong nanoseconds] 
TimeCdouble seconds) 
getNanoseconds 
getSeconds 

secondsToNanoseconds 



Duration 



getDuration 



AG ock uses a Ti meBase to keep track of the passage of time while a media 
stream is being presented. A TimeBase provides a constantly ticking time 
source much like a crystal oscillator in a watch. The only information that 
a Ti meBase provides is its current time, which is referred to as the time-base 



time. The time-base time cannot be stopped or re** Ti™ k«« *: . 
often based on the system clock. ^ Tune-base time is 

AG ock objecT s media time represents the current position within a ^ • 
sti-eam-the beginning of the stream is media L 

To keep track of the current media time, a Clock uses: 

* IlLT^ 3 ^f^^^e position in the media stream where 
presentation begins. 

example a rate of 1.0 represents the normal playback rate for the 

r^S^ will 
run at twice the normal rate. A negative rate indicates that the CI oc^fc 
running in the opposite direction from its Ti meBase-for example a 
negative rate might be used to play a media stream backward ' 

When presentation begins, the media time is mapped to the time-base 
time and the advancement of the time-base time is used to measure the 
passage of time. During presentation, the current media time is calculated 
using the following formula: «««-ui<«ea 

MediaTime = MediaStartTTme + RateCTimeBaseTime - TTmeBaseStartTime) 

When the presentation stops, the media time stops, but the time-base time 
continues to advance. If the presentation is restarted, the media time is 
remapped to the current time-base time. 

Managers 

The JMF API consists mainly of interfaces that define the behavior and 
mteracfaon of objects used to capture, process, and present time-based 
media. Implementations of these interfaces operate within the structure of 
the framework. By using intermediary objects called managers, JMF makes 
it easy to integrate new implementations of key interfaces that can be used 
seamlessly with existing classes. 



Understanding JMF 

JMF uses four managers: 
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• Manager-handles the construction of PI ayers, Processors 
DataSources, and DataSi nks. This level of indirection allows new 
implementations to be integrated seamlessly with JMF. From the client 
perspective these objects are always created the same w ^wSr 

^st^^ 

• Man ^ er - maint ains a registry of packages that contain JMF 
Da^nks ^ CUSt ° m Pl3yerS ' Processors ' ^Sources, and 

" deviaT eV1 " CeManager - mamtains a registry of available capture 

• PI uglnManager— maintains a registry of available JMF plue-in 
processing components, such as Multiplexers, Demultiplexers 
Codecs, Effects, and Renderers. 

P r08ram f ba f d on ^ you'" ^ed to use the Manager create 
methods to construct the Players, Processors, DataSources, and DataSi nks 
for your application. If you're capturing media data from an input device 
you 11 use the CaptureDevi ceManager to find out what devices are availabfe 
and access information about them. If you're interested in controlling 
what processing is performed on the data, you might also query the PI ug- 
lnManager to determine what plug-ins have been registered. 

^ 0 l eX ! en l J1 ^ h y implementing a new plug-in, you can 

register it with the PI uglnManager to make it available to Processors that 
support the plug-in API. To use a custom Player, Processor, DataSource 
or DataSi nk with JMF, you register your unique package prefix with the ' 
PackageManager. 



Event Model 



JMF uses a structured event reporting mechanism to keep JMF-based pro- 
grams informed of the current state of the media system and enable JMF- 
based programs to respond to media-driven error conditions, such as out- 
of data and resource unavailable conditions. Whenever a JMF object needs 
to report on the current conditions, it posts a MediaEvent. MediaEvent is 
subclassed to identify many particular types of events. These objects fol- 
low the established Java Beans patterns for events. 



16 



JMF API Guide 

For each type of JMF object that can post Medi aEvents IMFH^fir,^ 

Mg listener interface. Ibi^**^ 

posted, you implement the appropriate listener interfa™ • \ 



MediaEvent 



Controller 

addControl 1 erLi stene r 
removeControl lerLi stener 


has a I dontrol lerListener 

J control lerUpdateCControl lerEvent) 




V extei 


creates 
— ^ 


Control lertvent 








getSourceController 



SS? 1 " 0b,eCtS 3180 pOSt 6Vents - For more information, 
KIP Events" on page 122. 



see 



Data Model 

JMF media players usually use DataSources to manage the transfer of 
media-content. A DataSource encapsulates both the location of media and 
the protocol and software used to deliver the media. Once obtained the 
source cannot be reused to deliver other media. 

ADataSource is identified by either a JMF MediaLocator or a URL (univer- 
sal resource locator). A Medi aLocator is similar to a URL and can be con- 
structed from a URL, but can be constructed even if the corresponding 
protocol handler is not installed on the system. (In Java, a URL can only be 
constructed if the corresponding protocol handler is installed on the svs- 
tern.) J 

ADataSource manages a set of SourceStream objects. A standard data 
source uses a byte array as the unit of transfer. A buffer data source uses a 
Buffer object as its unit of transfer. JMF defines several types of Data- 
Source objects: 
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j Controls | [ Duration I 

I Data Source I manages one or more , i — - 

1 ^jj^ 1 * \ SourceStream J 



Figure 2-5: JMF data model 



-JPullPataSource | 

A 



AT 



juRLDataSource ~| 
- | Pull Buff erDataSou rce| 
- j PushDataSource J 
- j PushBufferDataSourcej 



PunSourceStream[ 
|lnputSourceStream j 



Pull Buff erStream| 
PushSourceStream | 
PushBufferStreamj 
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Push and Pull Data Sources 

Media data can be obtained from a variety of sources, such as local or net- 
work files and live broadcasts. JMF data sources can be categorized 
according to how data transfer is initiated: 

• Pull Data-Source-the client initiates the data transfer and controls the 

flowof data frompull data-sources. Established protocols forthistype 

of data include Hypertext Transfer Protocol (HTTP) and FILE IMF 

defines two types of pull data sources: PullDataSource and 

Pul 1 Buff erDataSource, which uses a Buffer object as its unit of 
transfer. 

• Push Data-Saurce-ihe server initiates the data transfer and controls 
the flow of data from a push data-source. Push data-sources include 
broadcast media, multicast media, and video-on-demand (VOD) For 
m?^ 038 ^ 3 ^ ° ne pr0tOC£>1 * me Rea l-°™e Transport Protocol 
mEm S Z d ! ve J°P ment b Y * e Intent Engineering Task Force 

for VOD. JMF defines two types of push data sources: PushDataSource 
and PushBufferDataSource, which uses a Buffer object as its unit of 
transfer. 



The degree of control that a client program can extend to the user depends 
on the type of data source being presented. For example, an MPEG file can 
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^Hpn^^ f d 3 diCnt P"*™ could alIow the user to replay the 
video clip or seek to a new position in the video In contrast b™7 f 

Specialty DataSources 

^™S CS ^°. tyPeS data source s, doneable data sources 

and merging data sources. sources 

t^ZZf? ^ < ? TO Can 1,6 USed to dones of either a pull or 
push DataSource. To create a cloneable DataSource, you call the E™L 

to clone. Once a DataSource has been passed to created oneableData 
Source you should only interact with the doneable DataSource and its 
dones; the original DataSource should no longer be used direSly 

2fin 6 p?n e data rT 6S ^P 16 ™ 1 * me SourceGoneable interface, which 
defines one method, createdone. By calling createdone, you can create 
any number of dones of the DataSource that was used to construc?Ae 
doneable DataSource. The dones can be controlled through the doneable 
DataSource used to create them- when connect, disconnect, starter 
stop is called on the doneable DataSource, the method calls are propa- 
gated to the clones. F p 

The dones don't necessarily have the same properties as the doneable 

Hon^H ? t0 *?? ° r ^Source. For example, a 

doneable data source created for a capture device might function as a 
master data source for its clones-in this case, unless the doneable data 
source is used, the dones won't produce any data. If you hook up both the 
cloneable data source and one or more dones, the dones will produce 
data at the same rate as the master. 

AMergingDataSource can be used to combine the SourceStreams from sev- 
eral DataSources into a single DataSource. This enables a set of Data- 
Sources to be managed from a single point of control-when connect 
di sconnect, start, or stop is called on the MergingDataSource, the method 
calls are propagated to the merged DataSources. 

To construct a MergingDataSource, you call the Manager createMerging- 
DataSource method and pass in an array that contains the data sources 
you want to merge. To be merged, all of the DataSources must be of the 
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Date Formats 

The exact media format of an object is represented by a Format obiert Th„ 
JMF extends Format to define audio- and video-specific formats. 



Format 



AudioFormat | 
Video Format I 

A 1 



FormatControl 



get Format 
setFormat 

getSupportedFormats 

isEnabled 

setEnabled 



IndexedCol o r Format | 
RGBFormat | 



YUVFormat 



] 



JPECFormat 



] 



H261Format 



] 



H263 Format 
Figure 2-6: JMF media formats. 

An Audi oFormat describes the attributes specific to an audio format, such 

as samp e rate, bits per sample, and number of channels. A Vi deoFormat 

encapsulates information relevant to video data. Several formats are 

denvedfrom VideoFormat to describe the attributes of common video 
formats, including; 

• IndexedColorFormat 

• RGBFormat 

• YUVFormat 

• 3 PEC Format 

• H261Format 



• H263Format 
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To receive notification of format changes from a Control 1 er, you imple- 
ment the Control 1 erLi stener interface and listen for FormatChangeEvents 
(For more information, see "Responding to Media Events" on page 54.) 

Controls 

JMF Control provides a mechanism for setting'and querying attributes of 
an object. A Control often provides access to a corresponding user inter- 
face component that enables user control over an object's attributes Many 
JMF objects expose Controls, including Controller objects, DataSource 
objects, DataSink objects, and JMF plug-ins. 

Any JMF object that wants to provide access to its corresponding Control 
objects can implement the Controls interface. Controls defines methods 
for retrieving associated Control objects. DataSource and PI ugln use the 
Controls interface to provide access to their Control objects. 

Standard Controls 

JMF defines the standard Control interfaces shown in Figure 2-8- "IMF 
controls." "' 

CachingControl enables download progress to be monitored and dis- 
played. If a Player or Processor can report its download progress, it 
implements this interface so that a progress bar can be displayed to the 
user. 

CainControl enables audio volume adjustments such as setting the level 
and muting the output of a PI ayer or Processor. It also supports a listener 
mechanism for volume changes. 



Medi aEvent 



has one or more 



CainControl 




GainChangeLi stener 






addCai nChanqeLi stener 
removeCai nCfiangeLi stener 


» 


gai nChangeCCai nChangeEvent) 








creates 
— k. 












GainChangetvent 






getDB 

getLevel 

getMute 



extends 



Figure 2-7: Gain control 
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f Control 



— jBitRateControl | 

— | Buff erCont rol | 

- Jcachi ngCont rol ] 

J FormatControl " | 

A ' 

' |TrackContro1 j 

- \ FraroeGrabbi ngContro l I 
- [FramePosi ti oni ngControl | 
- ) FrameProcessi ngContr ol I 
- | FrameRateControT [ 
- jCainControl ""] 
- |H263Contro1 | 
- jH261Contro1 | 
- ] KeyFrameControl "j 
- j Mom* torCont rol | 
-| MpegAudi oCont rol""| 
■I PacketSizeControT] 
PortControl | 
QualityContro l | 
RTPControl | 

" 1 SilenceSuppressionControlj 

1— 1 StreairtWriterControl | 

Figure 2-8: JMF controls. 

DataSink or Multiplexer objects that read media from a Da taSource and 
write it out to a destination such as a file can implement the St reamWri t- 
erControl interface. This Control enables the user to limit the size of the 
stream that is created. 

FramePosi ti oni ngCont rol and FrameCrabbingControl export frame-based 
capabilities for Players and Processors. FramePosi ti oni ngCont rol enables 
precise frame positioning within a Player or Processor object's media 
stream. FrameCrabbi ngControl provides a mechanism for grabbing a still 
video frame from the video stream. The FrameCrabbi ngControl can also be 
supported at the Renderer level. 
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Objects that have a Format can implement the FormatControl interface to 
provide access to the Format. FormatControl also provides methods for 
querying and setting the format. 

foJrnn^ll trGl *l ° f FormatContr <> 1 ** Provides the mechanism 
for contorting what processing a Processor object performs on a particu- 
lar track of media data. With the TrackControl methods, you can speti^ 
what format conversions are performed on individual tracks and select 
the Effect, Codec, or Renderer plug-ins that are used by the Processor 
{tor more ^formation about processing media data, see 'Trocessine ' 
Time-Based Media with JMF" on page 71.) 

Two controls, PortControl and Mom" torControl enable user control over 
the capture process. PortControl defines methods for controlling the out- 
put of a capture device. Moni torControl enables media data to be pre- 
viewed as it is captured or encoded. 

tifflto obSert 1 enaWeS USCr " leVel C ° ntrol OVer me buffe ring done by a par- 

JMF also defines several codec controls to enable control over hardware or 
software encoders and decoders: 

• BitRateControl— used to export the bit rate information for an 
incoming stream or to control the encoding bit rate. Enables 
specification of the bit rate in bits per second. 

• FrameProcessi ngControl— enables the specification of frame 
processing parameters that allow the codec to perform minimal 
processing when it is falling behind on processing the incoming data. 

• FrameRateControl— enables modification of the frame rate. 

• H261Control— enables control over the H.261 video codec still-image 
transmission mode. 

• H263Cont rol— enables control over the H.263 video-codec parameters 
including support for the unrestricted vector, arithmetic coding, 
advanced prediction, PB Frames, and error compensation extensions. 

• KeyFrameControl— enables the specification of the desired interval 
between key frames. (The encoder can override the specified key- 
frame interval if necessary.) 

• MpegAudioControl— exports an MPEG audio codec's capabilities and 
enables the specification of selected MPEG encoding parameters. 

• Qua! i tyControl— enables specification of a preference in the trade-off 
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^ality and CPU usage in the proofing performed by a 
codec This quality hint can have different effects depending on the 
type of compression. A higher quality setting will result in better 
quakty of the resulting bits, for example better image quality for 

• Si lenceSuppressionControl— enables specification of silence 
suppression parameters for audio codecs. When silence suppression 
mode is on, an audio encoder does not output any data if it detects 
silence at its input. 

User Interface Components 

A Control can provide access to a user interface Component that exposes its 
control behavior to the end user. To get the default user interface compo- 
nent for a particular Control, you call getControl Component. This method 
returns an AWT Component that you can add to your applet's presentation 
space or application window. 

A Control 1 er might also provide access to user interface Components For 
example, a Player provides access to both a visual component and a con- 
trol panel component— to retrieve these components, you call the Player 
methods getVisual Component and getControl Panel Component. 

If you don't want to use the default control components provided by a 
particular implementation, you can implement your own and use the 
event listener mechanism to determine when they need to be updated. For 
example, you might implement your own GUI components that support 
user interaction with a Player. Actions on your GUI components would 
trigger calls to the appropriate Player methods, such as start and stop. 
By registering your custom GUI components as Control 1 erLi steners for 
the PI ayer, you can also update your GUI in response to changes in the 
Player object's state. 
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Extensibility 

Advanced developers and technology providers can extend JMF function- 
ality in two ways: 

• By implementing custom processing components (plug-ins) that can be 
interchanged with the standard processing components used by a JMF 
Processor 
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• By directly implementing the Controller, Player, Processor 
DataSource, or DataSi nk interfaces 

Implementing a JMF plug-in enables you to customize or extend the cana- 
pes o a Processor without having to implement one from scratch ? 
Once a plug-m is registered with JMF, it can be selected as a processing 

teusTd to:^ Pr ° CeSSOr ** SUPPOrtS plUg " in ^ ^ Wins can 

• Extend or replace a Processor object's processing capability piecewise 
by selecting the individual plug-ins to be used. 

• Access the media data at specific points in the data flow. For example 
different Effect plug-ins can be used for pre- and post-processing of 
the media data associated with a Processor. 

• ProcessmediadataoutsideofaPlayerorProcessor.Forexample you 
mightuse a Demultiplexer plug-in to getindividual audio tracks from 
amultaplexed media-stream so you could play the tracks through Java 

In situations where an even greater degree of flexibility and control is 
required, custom implementations of the JMF Control 1 er, PI ayer Proces- 
sor, DataSource, or DataSi nk interfaces can be developed and used seam- 
lessly with existing implementations. For example, if you have a 
hardware MPEG decoder, you might want to implement a PI ayer that 
takes input from a DataSource and uses the decoder to perform the pars- 
ing, decoding, and rendering all in one step. Custom Players and Proces- 
sors can also be implemented to integrate media engines such as 
Microsoft's Media Player, Real Network's RealPlayer, and IBM's HotMe- 
dia with JMF. 

Note JMF Players and Processors are not required to support plue-ins 
P ug-ins won't work with JMF 1.0-based PI ayers and some Processor im- 
plementations might choose not to support them. The reference imple- 
mentation of JMF 2.0 provided by Sun Microsystems, Inc. and IBM 
Corporation fully supports the plug-in API. 



Presentation 

In JMF, the presentation process is modeled by the Control 1 er interface. 
Control 1 er defines the basic state and control mechanism for an object 
that controls, presents, or captures time-based media. It defines the phase 
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J^ir 3 m ! di l. COntr0ller L g0eS and P rovides a mechanism for con- 

tolling the transitions between those phases. A number of the operations 
that must be performed before media data can be presented can be rime 
consuming, so JMF allows programmatic control over when they occur 

A Controller posts a variety of controller-specific MediaEvents to provide 
notification of changes in its status. To receive events from a Control 1 er 
such as a Player, you implement the ControllerListener interface For 
more information about the events posted by a Controll er, see "Control- 
ler Events" on page 30. 

The JMF API defines two types of Control 1 ers: PI avers and Processors A 
Player or Processor is constructed for a particular data source and is nor- 
mally not re-used to present other media data. 
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MediaHandler 
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Figure 2-9: JMF controllers. 



Players 

A PI ayer processes an input stream of media data and renders it at a pre- 
cise time. A DataSource is used to deliver the input media-stream to the 
PI ayer.The rendering destination depends on the type of media being pre- 
sented. 




Figure 2-10: JMF player model. 
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A PI ayer does not provide any control over the processing that it performs 
or how it renders the media data. ^ s 



PI ayer supports standardized user control and relaxes some of the opera- 
tional restrictions imposed by Clock and Controller. 
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stop 

getMediaTime 
getTimeBase 
setTimeBase 
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•E 
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Duration 



getDuration 
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Figure 2-11: JMF players. 



Player States 

A Player can be in one of six states. The Clock interface defines the two 
primary states: Stopped and Started. To facilitate resource management, 
Controll er breaks the Stopped state down into five standby states: Unreal- 
ized, Realizing, Realized, Prefetching, and Prefetched. 



Stopped Started 

realize I 




Transition Events: 
RCE RealizeCompleteEvent 
PFCE PrefetehCompfeteEvent 
SE StopEvent 

Figure 2-12: Player states. 



Understanding JMF 

In normal operation, a PI ayer steps through each state until it reaches the 
b tar tea state: 

A PI ayer in the Unrealized state has been instantiated, but does not yet 
know anything about its media. When a media PI ayer is first created 
it is Unrealized. 

• When realize is called, a PI ayer moves from the Unrealized state into 
the Realizing state. A Realizing PI ayer is in the process of determining 
its resource requirements. During realization, a PI ayer acquires the 
resources that it only needs to acquire once. These might include 
rendering resources other than exclusive-use resources. (Exclusive- 
use resources are limited resources such as particular hardware 
devices that can only be used by one PI ayer at a time; such resources 
are acquired during Prefetching.) A Realizing Player often downloads 
assets over the network. 

• When a PI ayer finishes Realizing, it moves into the Realized state. A 
Realized PI ayer knows what resources it needs and information about 
the type of media it is to present. Because a Realized PI aye r knows how 
to render its data, it can provide visual components and controls. Its 
connections to other objects in the system are in place, but it does not 
own any resources that would prevent another Player from starting. 

• When prefetch is called, a Player moves from the Realized state into 
the Prefetching state. A Prefetching PI ayer is preparing to present its 
media. During this phase, the Pi ayer preloads its media data, obtains 
exclusive-use resources, and does whatever else it needs to do to 
prepare itself to play. Prefetching might have to recur if a PI ayer 
object's media presentation is repositioned, or if a change in the PI ayer 
objecf s rate requires that additional buffers be acquired or alternate 
processing take place. 

• When a PI ayer finishes Prefetching, it moves into the Prefetched state. A 
Prefetched PI ayer is ready to be started. 

• Calling start puts a PI ayer into the Started state. A Started PI ayer 
object's time-base time and media time are mapped and its clock is 
running, though the PI ayer might be waiting for a particular time to 
begin presenting its media data. 

A Player posts Transit! onEvents as it moves from one state to another. 
The ControllerListener interface provides a way for your program to 
determine what state a PI ayer is in and to respond appropriately. For 
example, when your program calls an asynchronous method on a PI ayer 
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or Processor, it needs to listen for the appropriate event to determine 
when the operation is complete. 

Using this event reporting mechanism, you can manage a PI aver object's 
start latency by controlling when it begins Realizing and Prefetching. It also 
enables you to determine whether or not the Player is in an appropriate 
state before calling methods on the PI ayer. 

Methods Available in Each Player State 

To prevent race conditions, not all methods can be called on a PI ayer in 
every state. The following table identifies the restrictions imposed by JMF. 
If you call a method that is illegal in a PI ayer object's current state, the 
PI ayer throws an error or exception. 



Method 


Unrealized 
Player 


Realt7pd 
Player 


a it re ten eu 
Player 


started 
Player 


addCont roller 


NotRealizedError 


legal 


legal 


ClockStartedError 


deallocate 


legal 


legal 


legal 


ClockStartedError 


getControl Panel Component 


NotRealizedError 


legal 


legal 


legal 


getCainControl 


NotRealizedError 


legal 


legal 


legal 


getStart Latency 


NotRealizedError 


legal 


legal 


legal 


getTi meBase 


NotRealizedError 


legal 


legal 


legal 


getVi sualComponent 


NotRealizedError 


legal 


legal 


legal 


mapToTi meBase 


CI ockStoppedExcept i on 


CI ockStoppedException 


CI ockStoppedExcepti on 


legal 


removeCont roller 


NotRealizedError 


legal 


legal 


ClockStartedError 


setMediaTime 


NotRealizedError 


legal 


legal 


legal 


setRate 


NotRealizedError 


legal 


legal 


legal 


setStopTime 


NotReal i zedError 


legal 


legal 


S t opTi me Set E r ro r 
if previously set 


setTi meBase 


NotReal i zedError 


legal 


legal 


CI ockStartedError 


syncStart 


NotPrefetchedError 


NotPrefetchedError 


legal 


CI ockStartedError 



Table 2-1: Method restrictions for players. 
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Processors 

Processors can also be used to present media data. A Processor is just a 
specialized type of PI ayer that provides control over what processing is 
performed on the input media stream. A Processor supports all of the 
same presentation controls as a PI ayer. 




Figure 2-13: JMF processor model. 

In addition to rendering media data to presentation devices, a Processor 
can output media data through a DataSource so that it can be presented by 
another Player or Processor, further manipulated by another Processor, 
or delivered to some other destination, such as a file. 

For more information about Processors, see "Processing" on page 32. 



Presentation Controls 

In addition to the standard presentation controls defined by Control 1 er, a 
Player or Processor might also provide a way to adjust the playback vol- 
ume. If so, you can retrieve its Cai nCont rol by calling getGai nControl . A 
GainControl object posts a GainChangeEvent whenever the gain is modi- 
fied. By implementing the Gai nChangeLi stener interface, you can respond 
to gain changes. For example, you might want to update a custom gain 
control Component. 

Additional custom Control types might be supported by a particular 
Player or Processor implementation to provide other control behaviors 
and expose custom user interface components. You access these controls 
through the getControl s method. 

For example, the CachingControl interface extends Control to provide a 
mechanism for displaying a download progress bar. If a PI ayer can report 
its download progress, it implements this interface. To find out if a Pi ayer 
supports CachingControl, you can call getControl (Cachi ngControl) or 
use getControl s to get a list of all the supported Control s. 



Standard User Interface Components 

A Player or Processor generally provides two standard user interface 

SSHTV *** C ° mp0nent " d 3 «««>H»«1 com^tu can 
acc^ these Components directly through the 9tW«io^S«^^ 

Control Panel Component methods. ■encanaget- 

J^^f 180 ^P 1 !^ «*r interface components, and use the 

event hstener mechanism to determine when they need to be updated! 

Controller Events 

Hie Control lerEvents posted by a Controller such as a Player or Proces- 
"tio" Categ ° rieS: ^ ******* ^se d events, and *an- 

• Change notification events such as RateChangeEvent 
^? 1 " ,, ** teEv «^and FormatChangeEvent indicate that some 
attribute of the Controller has changed, often inresponse toa method 
call. For example, a Player posts a RateChangeEvent when its rate is 
changed by a call to setRate. 

• Trans-i ti onEvents allow your program to respond to changes in a 
Controller object's state. A Player posts transition events whenever 
it moves from one state to another. (See "Player States" on page 26 for 
more information about the states and transitions.) 

• ControllerdosedEvents are posted by a Controller when it shuts 
down. When a Controller posts a ControllerdosedEvent, it is no 
longer usable. A Control! erErrorEvent is a special case of 
ControllerdosedEvent. You can listen for ControllerErrorEvents so 
that your program can respond to Control 1 er malfunctions to 
minimize the impact on the user. 
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StopAtTimeEvent | 



StopBy Request Event] 



- j DeallocateEvent | 



Figure 2-14: JMF events. 
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Processing 

A Processor is a Player that takes a DataSource as input, performs some 
user-defined processing on the media data, and then outputs the pro- 
cessed media data. r 



Player 



start 
setSource 
addCont roller 
getVi sual Component 
getCont rol Panel Component 



3 



has a 



DataSource 



extends 



Processor 



configure 
getTrackControls 
getSupportedContentOescri ptors 
setOutputContentDescri ptor 
getOutputContentDescri ptor 
getOataOutput 



creates a. 



DataSource 



Figure 2-15: JMF processors. 

A Processor can send the output data to a presentation device or to a 
DataSource. If the data is sent to a DataSource, that DataSource can be used 
as the input to another PI ayer or Processor, or as the input to a DataSi nk. 

While the processing performed by a PI ayer is predefined by the imple- 
mentor, a Processor allows the application developer to define the type of 
processing that is applied to the media data. This enables the application 
of effects, mixing, and compositing in real-time. 

The processing of the media data is split into several stages: 




Processor 



Figure 2-16: Processor stages. 



• Demultiplexing is the process of parsing the input stream. If the 
stream contains multiple tracks, they are extracted and output 
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separately. For example, a QuickTime file might be demultiplexed 
mto separate audio and video tracks. Demultiplexing is performed 
automatically whenever the input stream contains multiplexed data. 

• Pre-Processing is the process of applying effect algorithms to the 
tracks extracted from the input stream. 

• Transcoding is the process of converting each track of media data from 
one input format to another. When a data stream is converted from a 
compressed type to an uncompressed type, it is generally referred to 
as decoding. Conversely, converting from an uncompressed type to a 
compressed type is referred to as encoding. 

• Post-Processing is the process of applying effect algorithms to 
decoded tracks. 

• Multiplexing is the process of interleaving the transcoded media 
tracks into a single output stream. For example, separate audio and 
video tracks might be multiplexed into a single MPEG-1 data stream 
You can specify the data type of the output stream with the Processor 
se tOutputCon tent Desc ri ptor method. 

• Rendering is the process of presenting the media to the user. 

The processing at each stage is performed by a separate processing com- 
ponent. These processing components are JMF plug-ins. If the Processor 
supports TrackControl s, you can select which plug-ins you want to use to 
process a particular track. There are five types of JMF plug-ins: 

• Demul ti pi exe r— parses media streams such as WAV, MPEG or 
QuickTime. If the stream is multiplexed, the separate tracks are 
extracted. 

• Effect— performs special effects processing on a track of media data. 

• Codec — performs data encoding and decoding. 

• Mul ti pi exe r— combines multiple tracks of input data into a single 
interleaved output stream and delivers the resulting stream as an 
output DataSource. 

• Renderer— processes the media data in a track and delivers it to a 
destination such as a screen or speaker. 
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Processor States 



A Processor has two additional standby states, Configuring and Config- 
ured, which occur before the Processor enters the Realizing state.. 
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realize 




deallocate 

Transition Events: 
CCE ConfigureCompleteEvent 
KCE RealtzeCompfeteEvent 
PFCE PrefetchCompreteEvent 
SE StopEvent 

Figure 2-17: Processor states. 

• A Processor enters the Configuring state when configure is called. 
While the Processor is in the Configuring state, it connects to the 
DataSource, demultiplexes the input stream, and accesses information 
about the format of the input data. 

• The Processor moves into the Configured state when it is connected to 
the DataSource and data format has been determined. When the 
Processor reaches the Configured state, a Conf igureCompl eteEvent is 
posted. 

• When Real ize is called, the Processor is transitioned to the Real i zed 
state. Once the Processor is Realized it is fully constructed. 

While a Processor is in the Configured state, getTrackControls can be 
called to get the TrackControl objects for the individual tracks in the 
media stream. These TrackControl objects enable you specify the media 
processing operations that you want the Processor to perform. 

Calling realize directly on an Unrealized Processor automatically transi- 
tions it through the Configuring and Configured states to the Realized state 
When you do this, you cannot configure the processing options through 
the TrackControl s — the default Processor settings are used. 

Calls to the TrackControl methods once the Processor is in the Realized 
state will typically fail, though some Processor implementations might 
support them. 
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Methods Available in Each Processor State 
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Since a Processor is a type of PI ayer, the restrictions on when methods can 
be caUed on a PI ayer also apply to Processors. Some of the Processor-spe- 
cific methods also are restricted to particular states. The following table 



shows the restrictions that apply to a Processor. If you call a method that 
is illegal in the current state, the Processor throws an error or exception. 



Method 



Unrealized 
Processor 



Configuring 
Processor 



Configured 
Processor 



Realized 
Processor 



ad cfCont roller 


NotRealizedError 


NotRealizedError 


NotRealizedError 


legal 


deallocate 


legal 


legal 


legal 


legal 


getControl PaneKomponent 


NotRealizedError 


NotRealizedError 


NotReal izedError 


legal 


getControls 


legal 


legal 


legal 


legal 


getDataOutput 


NotRealizedError 


NotRealizedError 


NotRealizedError 


legal 


getCainControl 


NotRealizedError 


NotRealizedError 


NotRealizedError 


legal 


getOutputContentDescri ptor 


Not Con figured Error 


NotConf i guredError 


legal 


legal 


getSt art Latency 


NotRealizedError 


NotRealizedError 


NotRealizedError 


legal 


getSupportedContent- 
Descriptors 


legal 


legal 


legal 


legal 



getTimeBase 


NotRealizedError 


NotRealizedError 


NotRealizedError 


legal 


getTrackControls 


NotConf i gu redError 


NotConfi gu red Error 


legal 


FormatChange- 
Exception 


getVi sual Component 


NotRealizedError 


NotRealizedError 


NotRealizedError 


legal 


mapToTimeBase 


ClockStoppedExcepti on 


CI ockStoppedExcepti on 


CI ockStoppedExcepti on 


CI ockStopped- 
Excepti on 


realize 


legal 


legal 


legal 


legal 


removeCon t rol 1 e r 


NotRealizedError 


NotRealizedError 


NotRealizedError 


legal 


setOutputContentDescri ptor 


NotConfi gu redError 


NotConfi guredError 


legal 


FormatChange- 
Exception 


setMediaTime 


NotRealizedError 


NotRealizedError 


NotRealizedError 


legal 


setRate 


NotRealizedError 


NotRealizedError 


NotRealizedError 


legal 


setStopTime 


NotRealizedError 


NotRealizedError 


NotRealizedError 


legal 


setTimeBase 


NotRealizedError 


NotRealizedError 


NotRealizedError 


legal 


syncStart 


NotPrefetchedError 


NotPrefetchedError 


NotPrefetchedError 


NotPrefetchedError 



Table 2-2: Method restrictions for processors. 
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Processing Controls 

^ con ^l what processing operations the Processor performs on a 
track through the TrackControl for that track. You call Processor 

*** <°raUofthetracksin 

Through a TrackControl, you can explicitly select the Effect, Codec and 
tenderer p ug-ms you want to use for the track. To find out what options 

« £2£± you can w pl U9lnMana9er to out What 

To control the transcoding that's performed on a track by a particular 
Codec, you can get the Control s associated with the track by calling the 
TrackControl getControl s method. ITus method returns the codec con- 
trols available for the track, such as BitRateControl and QualityControl 
(For more information about the codec controls defined by IMF see "Con 
trols on page 20.) J ' 

If you know the output data format that you want, you can use the set- 
Format method to specify the Format and let the Processor choose an 
appropriate codec and renderer. Alternatively, you can specify the output 
format when the Processor is created by using a Processor-Model . A Pro- 
cessorModel defines the input and output requirements for a Processor 
When a ProcessorModel is passed to the appropriate Manager create 
method, the Manager does its best to create a Processor that meets the 
specified requirements. 

Data Output 

The getDataOutput method returns a Processor object's output as a Data- 
Source. This DataSource can be used as the input to another Player or Pro- 
cessor or as the input to a data sink. (For more information about data 
sinks, see "Media Data Storage and Transmission" on page 37.) 

A Processor object's output DataSource can be of any type: PushData- 
Source, PushBufferDataSource, Pull DataSource, or Pull Buff erDataSource. 

Not all Processor objects output data— a Processor can render the pro- 
cessed data instead of outputting the data to a DataSource. A Processor 
that renders the media data is essentially a configurable PI ayer. 
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Capture 

A multimedia capturing device can act as a source for multimedia data 
de ivery. For example, a microphone can capture raw audio input or a dig- 
ital video capture board might deliver digital video from a camera Such 
capture devices are abstracted as DataSources. For example, a device that 
provides timely delivery of data can be represented as a PushDataSource 
Any type of DataSource can be used as a capture DataSource: PushData- ' 
Source, PushBufferDataSource, Pull DataSource, or Pull Buff erDataSource. 

Some devices deliver multiple data streams-for example, an audio/ 
video conferencing board might deliver both an audio and a video stream 
The corresponding DataSource can contain multiple SourceStrearas that " 
map to the data streams provided by the device. 



Media Data Storage and Transmission 

A DataSi nk is used to read media data from a DataSource and render the 
media to some destination— generally a destination other than a presenta- 
tion device. A particular DataSi nk might write data to a file, write data 
across the network, or function as an RIP broadcaster. (For more informa- 
tion about using a DataSi nk as an RIP broadcaster, see "Transmitting RIP 
Data With a Data Sink" on page 149.) 

Like Players, DataSi nk objects are constructed through the Manager using 
a DataSource. A DataSi nk can use a StreamWriterControl to provide addi- 
tional control over how data is written to a file. See "Writing Media Data 
to a File" on page 74 for more information about how DataSi nk objects are 
used. 



Storage Controls 

A DataSi nk posts a DataSi nkEvent to report on its status. A DataSi nkEvent 
can be posted with a reason code, or the DataSi nk can post one of the fol- 
lowing DataSi nkEvent subtypes: 

• DataSi nkErrorEvent, which indicates that an error occurred while the 
DataSi nk was writing data. 

• EndOf StreamEvent, which indicates that the entire stream has 
successfully been written. 
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To respond to events posted by a DataSi nk, you implement the DataSi n- 
kListener interface. 



Extensibility 

You can extend JMF by implementing custom plug-ins, media handlers, 
and data sources. 



Implementing Plug-Ins 

By implementing one of the JMF plug-in interfaces, you can directly access 
and manipulate the media data associated with a Processor: 

• Implementing the Demul ti pi exer interface enables you to control how 
individual tracks are extracted from a multiplexed media stream. 

• Implementing the Codec interface enables you to perform the 
processing required to decode compressed media data, convert media 
data from one format to another, and encode raw media data into a 
compressed format. 

• Implementing the Effect interface enables you to perform custom 
processing on the media data. 

• Implementing the Mul ti pi exer interface enables you to specify how 
individual tracks are combined to form a single interleaved output 
stream for a Processor. 

• Implementing the Renderer interface enables you to control how data 
is processed and rendered to an output device. 

Note: The JMF Plug-In API is part of the official JMF API, but JMF PI ayers 
and Processors are not required to support plug-ins. Plug-ins won't work 
with JMF 1.0-based PI ayers and some Processor implementations might 
choose not to support them. The reference implementation of JMF 2.0 pro- 
vided by Sun Microsystems, Inc. and IBM Corporation fully supports the 
plug-in API. rr 

Custom Codec, Effect, and Renderer plug-ins are available to a Processor 
through the TrackControl interface. To make a plug-in available to a 
default Processor or a Processor created with a ProcessorModel, you need 
to register it with the PI uglnManager. Once you've registered your plug-in, 
it is included in the list of plug-ins returned by the PI uglnManager get- 
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PluglnLi st method and can be accessed by the Manager when it constructs 
a Processor object. 

Implementing MediaHandlers and DataSources 

If the JMF Plug-In API doesn't provide the degree of flexibility that you 
need, you can directly implement several of the key JMF interfaces: Con- 
troller, Player, Processor, DataSource, and DataSink. For example you 
might want to implement a high-performance PI ayer that is optimized to 
present a single media format or a Controller that manages a completely 
different type of time-based media. 

The Manager mechanism used to construct Player, Processor, DataSource, 
and DataSi nk objects enables custom implementations of these JMF inter- 
faces to be used seamlessly with JMF. When one of the create methods is 
called, the Manager uses a well-defined mechanism to locate and construct 
the requested object. Your custom class can be selected and constructed 
through this mechanism once you register a unique package prefix with 
the PackageManager and put your class in the appropriate place in the pre- 
defined package hierarchy. 



MediaHandler Construction 

PI ayers, Processors, and DataSi nks are all types of Medi aHandl ers— they 
all read data from a DataSource. A Medi aHandl er is always constructed for 
a particular DataSource, which can be either identified explicitly or with a 
MediaLocator. When one of the cr eateMediaHandTer methods is called, 
Manager uses the content-type name obtained from the DataSource to find 
and create an appropriate MediaHandler object. 
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Figure 2-18: JMF media handlers. 

JMF also supports another type of Medi aHandl er, Medi aProxy. A Medi aProxy 
processes content from one DataSource to create another. Typically, a Medi - 
aProxy reads a text configuration file that contains all of the information 
needed to make a connection to a server and obtain media data. To create 
a Player from a MediaProxy, Manager: 

1. Constructs a DataSource for the protocol described by the Medi aLocator 

2. Uses the content-type of the DataSource to construct a MediaProxy to 
read the configuration file. 

3. Gets a new DataSource from the MediaProxy. 

4. Uses the content-type of the new DataSource to construct a Player. 



The mechanism that Manager uses to locate and instantiate an appropriate 
Medi aHandl er for a particular DataSou rce is basically the same for all types 
of Medi aHandl ers: 
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• Using the list of installed content package-prefixes retrieved from 
PackageManager, Manager generates a search list of available 
MediaHandler classes. 

• Manager steps through each class in the search list until it finds a class 
named Hand! er that can be constructed and to which it can attach the 
DataSource. 

When constructing Players and Processors, Manager generates the search 
list of available handler classes from the list of installed content package- 
prefixes and the content-type name of the DataSource. To search for PI ay- 
ers, Manager looks for classes of the form: 

<content package-pref i x> . medi a . content . <content- typo . Hand! er 

To search for Processors, Manager looks for classes of the form: 

<content package-prefix>. media. processor. <content-type>. Handler 

If the located Medi aHandl er is a Medi aProxy, Manager gets a new DataSource 
from the MediaProxy and repeats the search process. 

If no appropriate Medi aHandl er can be found, the search process is 
repeated, substituting unknown for the content-type name. The unknown 
content type is supported by generic Players that are capable of handling 
a large variety of media types, often in a platform-dependent way. 

Because a DataSink renders the data it reads from its DataSource to an out- 
put destination, when a DataSi nk is created the destination must also be 
taken into account. When constructing DataSi nks, Manager uses the list of 
content package-prefixes and the protocol from the MediaLocator that 
identifies the destination. For each content package-prefix. Manager adds 
to the search list a class name of the form: 

<content package-pref ix>. media. datasink. protocol .Handler 

If the located Medi aHandl er is a DataSi nk, Manager instantiates it, sets its 
DataSource and Medi aLocator, and returns the resulting DataSi nk object. If 
the handler is a DataSi nkProxy, Manager retrieves the content type of the 
proxy and generates a list of DataSi nk classes that support the protocol of 
the destination Medialocator and the content type returned by the proxy: 

<content package-prefix>. media. datasink. protocol .<content-type>. Handler 

The process continues until an appropriate DataSi nk is located or the Man- 
ager has iterated through all of the content package-prefixes. 
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DataSource Construction 

Manager uses the same mechanism to construct DataSources that it uses to 
construct Medi aHandl ers, except that it generates the search list of Data- 
Source class names from the list of installed protocol package-prefixes. 

For each protocol package-prefix, Manager adds to the search list a class 
name of the form: 

protocol package-prefix>.media. protocol . <protocol>. DataSource 

Manager steps through each class in the list until it finds a DataSource that 
it can instantiate and to which it can attach the Medi aLocator. 
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Presenting Time-Based 
Media with JMF 



To present time-based media such as audio or video with JMF, you use a 
PI ayer. Playback can be controlled programmatically, or you can display a 
control-panel component that enables the user to control playback interac- 
tively. If you have several media streams that you want to play you need 
to use a separate PI ayer for each one. to play them in sync, you can use 
one of the PI ayer objects to control the operation of the others. 

A Processor is a special type of Player that can provide control over how 
the media data is processed before it is presented. Whether you're using a 
basic PI ayer or a more advanced Processor to present media content, you 
use the same methods to manage playback. For information about how to 
control what processing is performed by a Processor, see "Processing 
Time-Based Media with JMF" on page 71. 

The Medi aPl aye r bean is a Java Bean that encapsulates a JMF player to pro- 
vide an easy way to present media from an applet or application. The 
Medi aPl ayer bean automatically constructs a new Player when a different 
media stream is selected, which makes it easier to play a series of media 
clips or allow the user to select which media clip to play. For information 
about using the Medi aPl ayer bean, see "Presenting Media with the Media- 
Player Bean" on page 66 



Controlling a Player 

To play a media stream, you need to construct a PI ayer for the stream, con- 
figure the PI ayer and prepare it to run, and then start the PI ayer to begin 
playback. 
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Creating a Player 

You create a Player indirectly through the media Manager. To display the 
PI ayer, you get the PI ayer object's components and add them to your 
applet's presentation space or application window. 

When you need to create a new Player, you request it from the Manager by 
calling createPl ayer or createProcessor. The Manager uses the media URL 
or Medi aLocator that you specify to create an appropriate PI ayer. A URL 
can only be successfully constructed if the appropriate corresponding URL- 
StreamHandler is installed. Medi aLocator doesn't have this restriction. 

Blocking Until a Player is Realized 

Many of the methods that can be called on a PI ayer require the PI ayer to 
be in the Realized state. One way to guarantee that a PI ayer is Realized 
when you call these methods is to use the Manager createRealizedPlayer 
method to construct the PI ayer. This method provides a convenient way 
to create and realize a PI ayer in a single step. When this method is called, 
it blocks until the PI ayer is Realized. Manager provides an equivalent cre- 
ateRealizeProcessor method for constructing a Realized Processor. 

Note: Be aware that blocking until a PI ayer or Processor is Realized can 
produce unsatisfactory results. For example, if createReal i zedPl ayer is 
called in an applet, Appl et . start and Appl et . stop will not be able to 
interrupt die construction process. 

Using a ProcessorModel to Create a Processor 

A Processor can also be created using a ProcessorModel. The Processor- 
Model defines the input and output requirements for the Processor and the 
Manager does its best to create a Processor that meets these requirements. 
To create a Processor using a ProcessorModel, you call the Manager . cre- 
ateReal izedProcessor method. Example 3-1 creates a Realized Processor 
that can produce IMA4-encoded stereo audio tracks with a 44.1 kHz sam- 
ple rate and a 16-bit sample size. 

Example 3-1: Constructing a Processor with a ProcessorModel. 
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Since the ProcessorModel does not specify a source URL in this example 
Manager implicitly finds a capture device that can capture audio and then 
creates a Processor that can encode that into IMA4. 

Note that when you create a Realized Processor with a ProcessorModel you 
will not be able to specify processing options through the Processor 
objecf s TrackControl s. For more information about specifying processing 
options for a Processor, see "Processing Time-Based Media with JMF" on 
page 71. 



Displaying Media Interface Components 

A PI ayer generally has two types of user interface components, a visual 
component and a control-panel component. Some Player implementa- 
tions can display additional components, such as volume controls and 
download-progress bars. 



Displaying a Visual Component 

A visual component is where a PI ayer presents the visual representation 
of its media, if it has one. Even an audio Player might have a visual com- 
ponent, such as a waveform display or animated character. 

To display a Player object's visual component, you: 

1. Get the component by calling getVisual Component. 

2. Add it to the applef s presentation space or application window. 

You can access the PI ayer object's display properties, such as its x and y 
coordinates, through its visual component. The layout of the PI ayer com- 
ponents is controlled through the AWT layout manager. 



Displaying a Control Panel Component 

A PI ayer often has a control panel that allows the user to control the 
media presentation. For example, a PI ayer might be associated with a set 
of buttons to start, stop, and pause the media stream, and with a slider 
control to adjust the volume. 
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Every Player provides a default control panel. To display the default con- 
trol panel: 

1. Call getControl PanelComponent to get the Component. 

2. Add the returned Component to your applet's presentation space or ap- 
plication window. 

If you prefer to define a custom user-interface, you can implement custom 
GUI Components and call the appropriate Player methods in response to 
user actions. If you register the custom components as Control 1 erLi sten- 
ers, you can also update them when the state of the PI ayer changes. 

Displaying a Gain-Control Component 

Player implementations that support audio gain adjustments implement 
the Cai nControl interface. Gai nControl provides methods for adjusting the 
audio volume, such as setLevel and setMute. To display a Gai nControl 
Component if the Player provides one, you: 

1. Call getCai nControl to get the Cai nControl from the Player. If the 
Player returns null, it does not support the Cai nControl interface. 

2. Call getControl Component on the returned Cai nControl. 

3. Add the returned Component to your applet's presentation space or ap- 
plication window. 

Note that getControl s does not return a PI ayer object's Cai nControl . You 
can only access the Cai nControl by calling getCai nControl . 

Displaying Custom Control Components 

Many PI ayers have other properties that can be managed by the user. For 
example, a video PI ayer might allow the user to adjust brightness and 
contrast, which are not managed through the PI ayer interface. You can 
find out what custom controls a Player supports by calling the getCon- 
trol s method. 



For example, you can call getControl s to determine if a PI ayer supports 
the CachingControl interface. 
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Example 3-2: Using getControl s to find out what Control s are supported. 




Displaying a Download-Progress Component 

The CachingControl interface is a special type of Control implemented by 
Players that can report their download progress. A CachingControl pro- 
vides a default progress-bar component that is automatically updated as 
the download progresses. To use the default progress bar in an applet 

1. Implement the Control lerListener interface and listen for 
CachingControl Events in controllerUpdate. 

2. The first time you receive a CachingControl Event: 

a. Call getCachi ngControl on the event to get the caching control. 

b. Call getProgressBar on the Cachi ngControl to get the default 
progress bar component. 

c. Add the progress bar component to your applet's presentation 
space. 

3. Each time you receive a Cachi ngControl Event, check to see if the down- 
load is complete. When getContentProgress returns die same value as 
getContentLength, remove the progress bar. 

The PI ayer posts a CachingControl Event whenever the progress bar needs 
to be updated. If you implement your own progress bar component, you 
can listen for this event and update the download progress whenever 
Cachi ngControl Event is posted. 

Setting the Playback Rate 

The PI ayer objecf s rate determines how media time changes with respect 
to time-base time; it defines how many units a PI ayer object's media time 
advances for every unit of time-base time. The PI ayer object's rate can be 
thought of as a temporal scale factor. For example, a rate of 2.0 indicates 
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that media time passes twice as fast as the time-base time when the PI aver 
is started. y 



In theory, a Player object's rate could be set to any real number with 
ative rates interpreted as playing the media in reverse. However, 



neg- 



some 



media formats have dependencies between frames that make it impossi- 
ble or impractical to play them in reverse or at non-standard rates. 

To set the rate, you call setRate and pass in the temporal scale factor as a 
float value. When setRate is called, the method returns the rate that is 
actually set, even if it has not changed. PI ayers are only guaranteed to 
support a rate of 1.0. 



Setting the Start Position 

Setting a PI ayer object's media time is equivalent to setting a read posi- 
tion within a media stream. For a media data source such as a file, the 
media time is bounded; the maximum media time is defined by the end of 
the media stream. 

To set the media time you call setMedi aTi me and pass in a Ti me object that 
represents the time you want to set. 



Frame Positioning 

Some PI ayers allow you to seek to a particular frame of a video. This 
enables you to easily set the start position to the beginning of particular 
frame without having to specify the exact media time that corresponds to 
that position. Players that support frame positioning implement the 
FramePosi tioni ngControl. 

To set the frame position, you call the FramePosi tioni ngControl seek 
method. When you seek to a frame, the PI ayer object's media time is set 
to the value that corresponds to the beginning of that frame and a Medi a- 
TimeSetEvent is posted. 

Some PI ayers can convert between media times and frame positions. You 
can use the FramePosi tioni ngControl mapFrameToTimeand mapTimeToFrame 
methods to access this information, if if s available. (Players that support 
FramePosi tioni ngControl are not required to export mis information.) 
Note that there is not a one-to-one correspondence between media times 
and frames —a frame has a duration, so several different media times 
might map to the same frame. (See "Getting the Media Time" on page 53 
for more information.) 
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Preparing to Start 

Most media Players cannot be started instantly. Before the Player can 
start, certain hardware and software conditions must be met. For example, 
if the PI ayer has never been started, it might be necessary to allocate buff- 
ers in memory to store the media data. Or, if the media data resides on a 
network device, the PI ayer might have to establish a network connection 
before it can download the data. Even if the PI ayer has been started 
before, the buffers might contain data that is not valid for the current 
media position. 



Realizing and Prefetching a Player 

JMF breaks the process of preparing a PI ayer to start into two phases, 
Realizing and Prefetching. Realizing and Prefetching a PI ayer before you start 
it minimizes the time it takes the PI ayer to begin presenting media when 
start is called and helps create a highly-responsive interactive experience 
for me user. Implementing the Cont rol 1 erLi stener interface allows you to 
control when these operations occur. 

Note Processor introduces a third phase to the preparation process called 
Configuring. During this phase, Processor options can be selected to con- 
trol how the Processor manipulates the media data. For more informa- 
tion, see "Selecting Track Processing Options" on page 72. 

You call real i ze to move the PI ayer into the Realizing state and begin the 
realization process. You call prefetch to move the Player into the Prefetch- 
ing state and initiate the prefetching process. The realize and prefetch 
methods are asynchronous and return immediately. When the PI ayer 
completes the requested operation, it posts a RealizeCompleteEvent or 
PrefetchCompleteEvent. "Player States" on page 26 describes the opera- 
tions that a PI ayer performs in each of these states. 

A PI ayer in the Prefetched state is prepared to start and its start-up latency 
cannot be further reduced. However, setting the media time through set- 
MediaTime might return the Player to the Realized state and increase its 
start-up latency. 

Keep in mind that a Prefetched PI ayer ties up system resources. Because 
some resources, such as sound cards, might only be usable by one pro- 
gram at a time, having a PI ayer in the Prefetched state might prevent other 
Players from starting. 
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Determining the Start Latency 

To determine how much time is required to start a PI ayer, you can call 
getStartLatency. For Players that have a variable start latency, the return 
value of getStartLatency represents the maximum possible start latency. 
For some media types, getStartLatency might return LATENCY_UNKNOWN. 

The start-up latency reported by getStartLatency might differ depending 
on the Player object's current state. For example, after a prefetch opera- 
tion, the value returned by getStartLatency is typically smaller. A Con- 
trol 1 er that can be added to a PI ayer will return a useful value once it is 
Prefetched. (For more information, see "Using a Player to Synchronize 
Controllers" on page 57.) 

Starting and Stopping the Presentation 

The Clock and Player interfaces define the methods for starting and stop- 
ping presentation. 



Starting the Presentation 

You typically start the presentation of media data by calling start. The 
start method tells the Player to begin presenting media data as soon as 
possible. If necessary, start prepares the PI ayer to start by performing the 
realize and prefetch operations. If start is called on a Started Player, the 
only effect is that a StartEvent is posted in acknowledgment of the 
method call. 

Clock defines a syncStart method that can be used for synchronization. 
See "Synchronizing Multiple Media Streams" on page 56 for more infor- 
mation. 

To start a PI ayer at a specific point in a media stream: 

1. Specify the point in the media stream at which you want to start by call- 
ing setMediaTime. 

2. Call start on the PI ayer. 
Stopping the Presentation 

There are four situations in which the presentation will stop: 
• When the stop method is called 
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• When the specified stop time is reached 

• When there's no more media data to present 

• When the media data is being received too slowly for acceptable play- 
When a PI ayer is stopped, its media time is frozen if the source of the 
media can be controlled. If the Player is presenting staSdS^lt 
might not be possible to freeze the media time. In InTcZ o2 toe 
rec^pt ofthemedia data is stopped-^ 

and the media time continues to advance. 

When a Stopped PUyer is restarted, if the media time was frozen, presenta- 
tion resumes from the stop time. If media time could not be frozen when 

t Ve Zf St ° P1 F d ' re0eptiOn of me stream and playback 

begins with the newly-received data. pay dock 

To stop a Player immediately, you call the stop method. If you call stop on 
a Stopped PI ayer, the only effect is that a StopByRequestEvent is posted in 
acknowledgment of the method call. 

Stopping the Presentation at a Specified Time 

You can call setStopTirae to indicate when a Player should stop. The 
PI ayer stops when its media time passes the specified stop time If the 
Player object's rate is positive, the Player stops when the media time 
becomes greater than or equal to the stop time. If the PI ayer object's rate 
is negative, the Player stops when the media time becomes less than or 
equal to the stop time. The Player stops immediately if its current media 
time is already beyond the specified stop time. 

For example, assume that a Player object's media time is 5.0 and setStop- 
Time is called to set the stop time to 6.0. If the Player object's rate is posi- 
tive, media time is increasing and the PI ayer will stop when the media 
time becomes greater than or equal to 6.0. However, if the PI ayer object's 
rate is negative, it is playing in reverse and the PI ayer will stop immedi- 
ately because the media time is already beyond the stop time. (For more 
information about Player rates, see "Setting the Playback Rate" on 
page 47.) 

You can always call setStopTime on a Stopped Player. However, you can 
only set the stop time on a Started PI ayer if the stop time is not currently 
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set. If the Started Player already has a stop time, setStopTime throws an 
error. 

You can call getStopTime to get the currently scheduled stop time. If the 
clock has no scheduled stop time, getStopTime returns Clock. RESET. To 
remove the stop time so that the PI ayer continues until it reaches end-of- 
media, call setStopTi me (CI ock . RESET) . 

Releasing Player Resources 

The deal 1 ocate method tells a PI ayer to release any exclusive resources 
and minimize its use of non-exclusive resources. Although buffering and 
memory management requirements for PI ayers are not specified, most 
PI ayers allocate buffers that are large by the standards of Java objects. A 
well-implemented Player releases as much internal memory as possible 
when deallocate is called. 

The deallocate method can only be called on a Stopped Player. To avoid 
ClockStartedErrors, you should call stop before you call deallocate. 
Calling deal 1 ocate on a PI aye r in the Prefetching or Prefetched state returns 
it to the Realized state. If deal 1 ocate is called while the PI ayer is realizing, 
the Player posts a DeallocateEvent and returns to the Unrealized state. 
(Once a PI ayer has been realized, it can never return to the Unrealized 
state.) 

You generally call deal 1 ocate when the PI ayer is not being used. For 
example, an applet should call deal! ocate as part of its stop method. By 
calling deall ocate, the program can maintain references to the PI ayer, 
while freeing other resources for use by the system as a whole. (JMF does 
not prevent a Realized PI ayer that has formerly been Prefetched or Started 
from maintaining information that would allow it to be started up more 
quickly in the future.) 

When you are finished with a PI ayer (or any other Con troll er) and are 
not going to use it anymore, you should call cl ose. The cl ose method 
indicates that the Control 1 er will no longer be used and can shut itself 
down. Calling close releases all of the resources that the Controller was 
using and causes it to cease all activity When a Control 1 er is closed, it 
posts a Control 1 erCl osedEvent. A closed Control 1 er cannot be reopened 
and invoking methods on a closed Control 1 er might generate errors. 
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Getting the Time-Base Time 

You can get a PI ayer object's current time-base time by getting the PI aver 
object's TimeBase and calling getTime: mgtnepiayer 

myCurrentTBTime = playerl.getTimeBaseO.getTimeO; 

When a PI ayer is running, you can get the time-base time that corre- 
sponds to a particular media time by calling mapToTimeBase. 



Getting the Duration of the Media Stream 

Since programs often need to know how long a particular media stream 
wiU run, all Controll ers implement the Duration interface. This interface 
defines a smgle method, getDuration. The duration represents the length 
of tune that a media object would run, if played at the default rate of 1 0 A 
media stream's duration is only accessible through a PI ayer. 

If the duration can't be determined when getDuration is called 
DURATTONJJNKNOWN is returned. This can happen if the PI ayer has not yet 
reached a state where the duration of the media source is available At a 
later time, the duration might be available and a call to getDuration 
would return the duration value. If the media source does not have a 
denned duration, as in the case of a live broadcast, getDuration returns 
DURATIONJJNBOUNDED. 



Responding to Media Events 

Control 1 erLi stener is an asynchronous interface for handling events gen- 
erated by Control 1 er objects. Using the Control 1 erLi stener interface 
enables you to manage the timing of potentially time-consuming Player 
operations such as prefetching. 

Implementing the ControIIerListener Interface 

To implement the Control 1 erLi stener interface, you need to: 

1. Implement the ControIIerListener interface in a class. 

2. Register that class as a listener by calling addControl 1 erLi stener on the 
Control! er that you want to receive events from. 
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When a Control 1 er posts an event, it calls control 1 erUpdate on each 
tered listener. 



regis- 



Typically, control 1 erUpdate is implemented as a series of if-else state- 
ments. 



Example 3-3:Implementing control! erUpdate 




This filters out the events that you are not interested in. If you have regis- 
tered as a listener with multiple Controllers, you also need to determme 
which Controller posted the event. Control! erEvents come "stamped" 
with a reference to their source that you can access by calling getSource. 

When you receive events from a Controller, you might need to do some 
additional processing to ensure that the Controller is in the proper state 
before calling a control method. For example, before calling any of the 
methods that are restricted to Stopped Players, you should check the 
Player objecf s target state by calling getTargetState. If start has been 
called, the Player is considered to be in the Started state, though it might 
be posting transition events as it prepares the PI ayer to present media. 

Some types of Control 1 erEvents contain additional state information. For 
example, the StartEvent and StopEvent classes each define a method that 
allows you to retrieve the media time at which the event occurred. 

Using ControIlerAdapter 

Control 1 erAdapter is a convenience class that implements Control 1 erLi s- 
tener and can be easily extended to respond to particular Events. To 
implement the Control 1 erLi stener interface using Control! erAdapter, 
you need to: 

1. Subclass ControIlerAdapter and override the event methods for the 
events that you're interested in. 

2. Register your Control 1 erAdapter class as a listener for a particular Con- 
troller by calling addControllerListener. 



56 



JMF API Guide 

When a Control 1 er posts an event, it calls control 1 erUpdate on each regis- 
tered listener. Cont roll er Adapter automatically dispatches the event to 
the appropriate event method, filtering out the events that you're not 
mterested in. 

For example, the following code extends a Control 1 erAdapter with a TDK 
1.1 anonymous inner-class to create a self-contained PI ayer that is auto- 
matically reset to the beginning of the media and deallocated when the 
Player reaches the end of the media. 



Example 3-4: Using Control 1 erAdapter. 




If you register a single ControllerAdapter as a listener for multiple Play- 
ers, in your event method implementations you need to determine which 
PI ayer generated the event. You can call getSource to determine where a 
Control 1 erEvent originated. 



Synchronizing Multiple Media Streams 

To synchronize the playback of multiple media streams, you can synchro- 
nize the PI ayers by associating them with the same Ti meBase. To do this, 
you use the getTimeBase and setTimeBase methods defined by the Clock 
interface. For example, you could synchronize pi ayerl with pi ayer2 by 
setting pi ayerl to use pi ayer2 * s time base: 

pi ayerl. setTimeBase (pi ayer 2 . getTi meBase ()) ; 

When you synchronize Players by associating them with the same Time- 
Base, you must still manage the control of each PI ayer individually. 
Because managing synchronized Players in this way can be complicated, 
JMF provides a mechanism that allows a PI ayer to assume control over ' 
any other Control 1 er. The PI ayer manages the states of these Control 1 ers 
automatically, allowing you to interact with the entire group through a 
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single point of control. For more information, see See "Using a Player to 
Synchronize Controllers". 5 Aid ' crra 



Using a Player to Synchronize Controllers 

Synchronizing Players directly using syncStart requires that you care- 
fuUy manage the states of all of the synchronized Players You must con 
tro eachonemdividu^^ 

on them as appropriate. Even with only a few PI ayers, this quickly 
becomes a difficult task. Through the Player interface, JMF provides a 
simpler solution: a Player can be used to manage the operation of any 
Controller. J 

When you interact with a managing Player, your instructions are auto- 
matically passed along to the managed Controllers as appropriate The 
managing PI ay e r takes care of the state management and synchronization 
for all of the other Cont roll ers. 

This mechanism is implemented through the addController and remove- 
Controller methods. When you call addController on a Player the Con- 
troller you specify is added to the list of Controllers managed by the 
Player. Conversely, when you call removeCont roller, the specified Con- 
troller is removed from the list of managed Control! ers. 

Typically, when you need to synchronize PI ayers or other Control 1 ers 
you should use this addController mechanism. It is simpler, faster, and' 
less error-prone than attempting to manage synchronized Players indi- 
vidually. 

When a Player assumes control of a Controller: 

• The Controller assumes the Player object's time base. 

• The PI ayer objecf s duration becomes the longer of the Control 1 er 
objecf s duration and its own. If multiple Controll ers are placed un- 
der a Player object's control, the Player object's duration is set to 
longest duration. 

• The PI ayer objecf s start latency becomes the longer of the Cont roll er 
object's start latency and its own. If multiple Controll ers are placed 
under a PI ayer object's control, the PI ayer object's start latency is set 
to the longest latency. 

A managing Player only posts completion events for asynchronous meth- 
ods after each of its managed Controllers have posted the event. The 
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managing Player reposts other events generated by the Controllers as 
appropriate. 

Adding a Controller 

You use the addCont roller method to add a Controller to the list of Con- 
trol lers managed by a particular PI ayer. To be added, a Control 1 er must 
be in the Realized state; otherwise, a NotRealizedError is thrown Two 
Players cannot be placed under control of each other. For example if 
pl ayerl is placed under the control of pi ayerZ, pi ayerZ cannot be placed 
under the control of playerl without first removing playerl from 
player2's control. 

Once a Controller has been added to a Player, do not call methods 
directly on the managed Controller. To control a managed Controller 
you interact with the managing PI ayer. 

To have player2 assume control of playerl, call: 
player2 . addController(playerl) ; 

Controlling Managed Controllers 

To control the operation of a group of Control 1 ers managed by a particu- 
lar PI ayer, you interact directly with the managing PI ayer. 

For example, to prepare all of the managed Control 1 ers to start call 
prefetch on the managing PI ayer. Similarly, when you want to start them, 
call start on the managing Player. The managing Player makes sure that 
all of the Control 1 ers are Prefetched, determines the maximum start 
latency among the Controllers, and calls syncStart to start them, specify- 
ing a time that takes the maximum start latency into account. 

When you call a Controller method on the managing Player, the Player 
propagates the method call to the managed Controllers as appropriate. 
Before calling a Controller method on a managed Controller, the Player 
ensures that the Controll er is in the proper state. The following table 
describes what happens to the managed Controllers when you call con- 
trol methods on the managing Player. 



Presenting Time-Based Media with JMF 



Function 

setMediaTime 



Stopped Player 



Started Player 



Invokes setMediaTime on all man- Stops all managed Controllers in- 
aged Controllers. vokes setMediaTime, and restart 

Controllers. 



setRate 



start 



realize 



prefetch 



stop 



deallocate 



setStopTime 



syncStart 



close 



Invokes setRate on all managed 
Control 1 ers. Returns the actual 
rate that was supported by all Con- 
trollers and set. 



Ensures all managed Controllers 
are Prefetched and invokes sync- 
Start on each of them, taking into 
account their start latencies. 



Stops all managed Control 1 ers, in- 
vokes setRate, and restarts Control- 
lers. Returns the actual rate that 
was supported by all Controllers 
and set. 

Depends on the Player implementa- 
tion. PI aye r might immediately post 
a StartEvent. 



The managing PI ayer immediate- The managing PI aver immediately 



ly posts a Real izeCompleteEvent 
To be added, a Controller must 
already be realized. 

Invokes prefetch on all managed 
Controllers. 



No effect. 



Invokes deal locate on all man- 
aged Controllers. 

Invokes setStopTime on all man- 
aged Control lers. (PI ayer must be 
Realized.) 

Invokes syncStart on all managed 
Controllers. 

Invokes close on all managed 
Controllers. 



posts a Real i zeCompl eteEvent. To be 
added, a Controller must already 
be realized. 

The managing Player immediately 
posts a PrefetchCompl eteEvent, in- 
dicating that all managed Control- 
ler s are Prefetched. 

Invokes stop on all managed Con- 
trollers. 

It is illegal to call deal 1 ocate on a 
Started Player. 

Invokes setStopTi me on all managed 
Control! ers. (Can only be set once 
on a Started Player.) 

It is illegal to call syncStart on a 
Started Player. 

It is illegal to call close on a. Started 
PI ayer. 



Table 3-1: Calling control methods on a managing player. 



Removing a Controller 



You use the removeCont roller method to remove a Controller from the 
list of controllers managed by a particular PI ayer. 
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To have pi ayer2 release control of pi ayerl, call: 
player2. removeCont roller (pi aye rl) ; 

Synchronizing Players Directly 

In a few situations, you might want to manage the synchronization of 
multiple PI ayer objects yourself so that you can control the rates or media 
times independently If you do this, you must: 

1. Register as a listener for each synchronized PI ayer. 

2. Determine which PI ayer object's time base is going to be used to drive 
the other Player objects and set the time base for the synchronized 
Player objects. Not all Player objects can assume a new time base. 
For example, if one of the PI ayer objects you want to synchronize has 
a push data-source, that Player object's time base must be used to 
drive the other Player objects. 

3. Set the rate for all of the PI ayer s. If a PI ayer cannot support the rate you 
specify, it returns the rate that was used. (There is no mechanism for 
querying the rates that a PI ayer supports.) 

4. Synchronize the states of all of the PI ayer objects. (For example, stop all 
of the players.) 

5. Synchronize the operation of the Player objects: 

• Set the media time for each PI ayer. 

• Prefetch each Player. 

• Determine the maximum start latency among the synchronized 
Player objects. 

• Start the Player objects by calling syncStart with a time that takes 
into account the maximum latency. 

You must listen for transition events for all of the PI ayer ob j ects and 
keep track of which ones have posted events. For example, when you 
prefetch the PI ayer objects, you need to keep track of which ones have 
posted PrefetchComplete events so that you can be sure all of them are 
Prefetched before calling syncStart. Similarly, when you request that the 
synchronized PI ayer objects stop at a particular time, you need to listen 
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for the stop event posted by each Player to determine when all of them 
have actually stopped. 

In some situations, you need to be careful about responding to events 
posted by the synchronized PI ayer objects. To be sure of the state of all of 
the Player objects, you might need to wait at certain stages for all of them 
to reach the same state before continuing. 

For example, assume that you are using one PI ayer to drive a group of 
synchronized PI ayer objects. A user interacting with that Player sets the 
media time to 10, starts the PI ayer, and then changes the media time to 20. 
You then: 

1. Pass along the first setMedi aTi me call to all of the synchronized PI ayer 
objects. 

2. Call prefetch on each PI ayer to prepare them to start. 

3. Call stop on each PI ayer when the second set media time request is re- 
ceived. 

4. Call setMedi aTi me on each Player with the new time. 

5. Restart the prefetching operation. 

6. When all of the Player objects have been prefetched, start them by call- 
ing syncStart, taking into account their start latencies. 

In this case, just listening for Pref etchComplete events from all of die 
PI ayer objects before calling syncStart isn't sufficient. You can't tell 
whether those events were posted in response to the first or second 
prefetch operation. To avoid this problem, you can block when you call 
stop and wait for all of the PI ayer objects to post stop events before con- 
tinuing. This guarantees that the next Pref etchComplete events you 
receive are the ones that you are really interested in. 



Example: Playing an MPEG Movie in an Applet 

The sample program PlayerAppl et demonstrates how to create a PI ayer 
and present an MPEG movie from within a Java applet. This is a general 
example that could easily be adapted to present other types of media 
streams. 
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The Player object's visual presentation and its controls are displayed 
within the applef s presentation space in the browser window. If you cre- 
ate a PI ayer in a Java application, you are responsible for creating the win- 
dow to display the PI ayer object's components. 

Note: While PlayerApplet illustrates the basic usage of a Player, it does 
not perform the error handling necessary in a real applet or application. 
For a more complete sample suitable for use as a template, see "JMF 
Applet" on page 173. 

Overview of PlayerApplet 

The APPLET tag is used to invoke PI ayerAppl et in an HTML file. The WIDTH 
and HEIGHT fields of the HTML APPLET tag determine the dimensions of the 
applef s presentation space in the browser window. The PARAM tag identi- 
fies the media file to be played. 



Example 3-5: Invoking PI ayerAppl et. 




When a user opens a web page containing PI ayerAppl et, the applet loads 
automatically and runs in the specified presentation space, which contains 
the PI ayer objecf s visual component and default controls. The PI ayer 
starts and plays the MPEG movie once. The user can use the default 
PI ayer controls to stop, restart, or replay the movie. If the page containing 
the applet is closed while the PI ayer is playing the movie, the PI ayer auto- 
matically stops and frees the resources it was using. 

To accomplish this, PI ayerAppl et extends Appl et and implements the Con- 
trol 1 erLi stener interface. PI ayerAppl et defines five methods: 

• i ni t — creates a PI aye r for the file that was passed in through the PARAM 
tag and registers PI ayerAppl et as a controller listener so that it can ob- 
serve media events posted by the PI ayer. (This causes the PI ayerAp- 
pl et control 1 erUpdate method to be called whenever the PI ayer posts 
an event.) 

• start — starts the PI ayer when PI ayerAppl et is started. 

• stop — stops and deallocates the PI ayer when PI ayerAppl et is 
stopped. 

• destroy — closes the Player when PlayerApplet is removed. 
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• control 1 erUpdate— responds to PI ayer events to display the PI ayer 
objecf s components. 

Example 3-6: PlayerApplet. 
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Initializing the Applet 

When a Java applet starts, its i ni t method is invoked automatically. You 
override i ni t to prepare your applet to be started. PI ayerAppl et performs 
four tasks in i nit: 

1. Retrieves the applet's FILE parameter. 

2. Uses the FILE parameter to locate the media file and build a URL object 
that describes that media file. 

3. Creates a Player for the media file by calling Manager.createPlayer. 

4. Registers the applet as a controller listener with the new PI ayer by call- 
ing addControl 1 erLi s tener. Registering as a listener causes the PI ayer- 
Appl et controller-Update method to be called automatically whenever 
the PI ayer posts a media event. The PI ayer posts media events when- 
ever its state changes. This mechanism allows you to control the PI ayer 
objecf s transitions between states and ensure that the PI ayer is in a 
state in which it can process your requests. (For more information, see 
"Player States" on page 26.) 



Example 3-7: Initializing Pi ayerAppl et. 
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Controlling the Player 

The Applet class defines start and stop methods that are called automati- 
cally when the page containing the applet is opened and closed. You over- 
ride these methods to define what happens each time your applet starts 
and stops. 

PI ayerAppl et implements start to start the PI ayer whenever the applet is 
started. 



Example 3-8: Starting the PI ayer in PI ayerAppl et. 




Deallocating the PI ayer releases any resources that would prevent another 
PI ayer from being started. For example, if the PI ayer uses a hardware 
device to present its media, deallocate frees that device so that other 
Players can use it. 

When an applet exits, destroy is called to dispose of any resources created 
by the applet. PI ayerAppl et overrides destroy to close the PI ayer. Closing 
a PI ayer releases all of the resources that if s using and shuts it down per- 
manently. 

Example 3-10: Destroying the Player in PI ayerAppl et. 
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Responding to Media Events 

PI ayerAppl et registers itself as a Control 1 erLi stener in its i ni t method so 
that it receives media events from the PI ayer. To respond to these events, 
PI ayerAppl et implements the control! erUpdate method, which is called' 
automatically when the Player posts an event. 

PI ayerAppl et responds to one type of event, Real i zeCompl eteEvent. When 
the Player posts a Real i zeCompl eteEvent, PlayerApplet displays the 
Player object's components. 



Example 3-11: Responding to media events in PI ayerAppl et. 




A PI ayer object's user-interface components cannot be displayed until the 
Player is Realized; an Unrealized Player doesn't know enough about its 
media stream to provide access to its user-interface components. PI ayer- 
Appl et waits for the Player to post a Real i zeCompl eteEvent and then dis- 
plays the PI ayer object's visual component and default control panel by 
adding them to the applet container. Calling vali date triggers the layout 
manager to update the display to include the new components. 

Presenting Media with the MediaPlayer Bean 

Using the Medi aPl aye r Java Bean (javax . medi a . bean . pi aye rbean . Medi a- 
Pl ayer) is the simplest way to present media streams in your applets and 
applications. MediaPlayer encapsulates a full-featured JMF Player in a 
Java Bean. You can either use the Medi aPl ayer bean's default controls or 
customize its control Components. 

One key advantage to using the Medi aPlayer bean is that it automatically 
constructs a new PI ayer when a different media stream is selected for 
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Media Streams 



To send or receive a live media broadcast or conduct a video conference 
over the Internet or Intranet you need to be able to receive and transmit 
media streams in real-time. This chapter introduces streaming media cor, 
cepts and describes the Real-time Transport Protocol JMF uses for receiv- 
ing and transmitting media streams across the network. 



Streaming Media 

When media content is streamed to a client in real-time, the client can 
begin to play the stream without having to wait for the complete stream to 
download. In fact, the stream might not even have a predefined dura- 
tion—downloading the entire stream before playing it would be impossi- 
ble. The term streaming media is often used to refer to both mis technique of 
delivering content over the network in real-time and the real-time media 
content that's delivered. 

Streaming media is everywhere you look on the web — live radio and tele- 
vision broadcasts and webcast concerts and events are being offered by a 
rapidly growing number of web portals, and if s now possible to conduct 
audio and video conferences over the Internet. By enabling the delivery of 
dynamic, interactive media content across the network, streaming media 
is changing the way people communicate and access information. 

Protocols for Streaming Media 

Transmitting media data across the net in real-time requires high network 
throughput. If s easier to compensate for lost data than to compensate for 
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large delays in receiving the data. This is very different from accessing 
static data such as a file, where the most important thing is that all of the 
data arrive at its destination. Consequently, the protocols used for static 
data don't work well for streaming media. 

The HTTP and FTP protocols are based on the Transmission Control Pro- 
tocol (TCP). TCP is a transport-layer protocol 1 designed for reliable data 
communications on low-bandwidth, high-error-rate networks. When a 
packet is lost or corrupted, if s retransmitted. The overhead of guarantee- 
ing reliable data transfer slows the overall transmission rate. 

For this reason, underlying protocols other than TCP are typically used for 
streaming media. One that's commonly used is the User Datagram Proto- 
col (UDP). UDP is an unreliable protocol; it does not guarantee that each 
packet will reach its destination. There's also no guarantee that the pack- 
ets will arrive in the order that they were sent. The receiver has to be able 
to compensate for lost data, duplicate packets, and packets that arrive out 
of order. 

Like TCP, UDP is a general transport-layer protocol— a lower-level net- 
working protocol on top of which more application-specific protocols are 
built. The Internet standard for transporting real-time data such as audio 
and video is the Real-Time Transport Protocol (RTP). 

RTP is defined in IETF RFC 1889, a product of the AVT working group of 
the Internet Engineering Task Force (IETF). 



Real-Time Transport Protocol 

RTP provides end-to-end network delivery services for the transmission 
of real-time data. RTP is network and transport-protocol independent, 
though it is often used over UDP. 



In the seven layer ISO/ OSI data communications model, the transport layer is level 
four. For more information about the ISO /OSI model, see Understanding OSI. 
Larmouth, John. International Thompson Computer Press, 1996. ISBN 1850321760. 
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Figure 7-1: RIP architecture 



RTP can be used over both unicast and multicast network services. Over a 
untcast network service, separate copies of the data are sent from the 
source to each destination. Over a multicast network service, the data is 
sent from the source only once and the network is responsible for trans- 
mitting the data to multiple locations. Multicasting is more efficient for 
many multimedia applications, such as video conferences. The standard 
Internet Protocol (IP) supports multicasting. 



RTP Services 



RTP enables you to identify the type of data being transmitted, determine 
what order the packets of data should be presented in, and synchronize 
media streams from different sources. 

RTP data packets are not guaranteed to arrive in the order that they were 
sent— in fact, they're not guaranteed to arrive at all. Ifs up to the receiver 
to reconstruct the sender's packet sequence and detect lost packets using 
the information provided in the packet header. 

While RTP does not provide any mechanism to ensure timely delivery or 
provide other quality of service guarantees, it is augmented by a control 
protocol (RTCP) that enables you to monitor the quality of the data distri- 
bution. RTCP also provides control and identification mechanisms for 
RTP transmissions. 

If quality of service is essential for a particular application, RTP can be 
used over a resource reservation protocol that provides connection-ori- 
ented services. 



RTP Architecture 

^ ^SE^* 8 ^ong a set of applications communicat- 

ing w,A RIP. A session is identified by a network address andTpTo * 

SoodS 01 * 18 for Ae media data and *" other is used contro1 

vIZT V T iS 3 SinglC ""^ host ' or Participating in the session, 
rarhapation m a session can consist of passive reception of data 
(receiver), active transmission of data (sender), or both. 

Each media type is transmitted in a different session. For example, if both 
audio and video are used in a conference, one session is used to transmit 
the audio data and a separate session is used to transmit the video data 
This enables participants to choose which media types they want to 
receive— for example, someone who has a low-bandwidth network con- 
nection might only want to receive the audio portion of a conference. 

Data Packets 

The media data for a session is transmitted as a series of packets. A series 
of data packets that originate from a particular source is referred to as an 
KTP stream. Each RTP data packet in a stream contains two parts, a struc- 
tured header and the actual data (the packer's payload). 

BitO 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 16 7 8 9 0 1 2 3 4 5 6 7 8 9 0 31 
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PT 



Sequence Number 



Timestamp 



Synchronization Source (SSRC) 



Content Source (CSRC) 
(0-15) 



Figure 7-2: RTP data-packet header format 

The header of an RTP data packet contains: 

• The RTP version number (V): 2 bits. The version defined by the cur- 
rent specification is 2. 
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Jtl^ 8 } ) ^ t adding bit iS mere are ° ne «■ more bytes 
at the end of the packet that are not part of the payload. Hie very iZ 
byte in the packet indicates the number of bytes of padding. ThY 
padding is used by some encryption algorithms. 

• Extension (X): 1 bit. If the extension bit is set, the fixed header is fol- 
lowed by one header extension. This extension mechanism enables 
implementations to add information to the RTP Header. 

• l C 5T^ (a 2 i bitS ' ^ number ^ CSRC identifiers that follow 
thefixed header If the CSRC count is zero, the synchronization source 
is the source of the payload. 

• Marker (M): 1 bit. A marker bit defined by the particular media 
profile. 

• Payload Type (PT): 7 bits. An index into a media profile table that 
describes the payload format. The payload mappings for audio and 
video are specified in RFC 1890. 

• Sequence Number 16 bits. A unique packet number that identifies 
this packef s position in the sequence of packets. The packet number 
is incremented by one for each packet sent 

• Timestamp: 32 bits. Reflects the sampling instant of the first byte in 
the payload. Several consecutive packets can have the same 
timestamp if they are logically generated at the same time— for 
example, if they are all part of the same video frame. 

• SSRC 32 bits. Identifies the synchronization source. If the CSRC count 
is zero, the payload source is the synchronization source. If the CSRC 
count is nonzero, the SSRC identifies the mixer. 

• CSRC: 32 bits each. Identifies the contributing sources for the payload. 
The number of contributing sources is indicated by the CSRC count 
field; there can be up to 16 contributing sources. If there are multiple 
contributing sources, the payload is the mixed data from those 
sources. 



Control Packets 

In addition to the media data for a session, control data (RTCP) packets 
are sent periodically to all of the participants in the session. RTCP packets 
can contain information about the quality of service for the session partic- 
ipants, information about the source of the media being transmitted on the 
data port, and statistics pertaining to the data that has been transmitted so 
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There are several types of RTCP packets: 

• Sender Report 

• Receiver Report 

• Source Description 

• Bye 

• Application-specific 

RTCP packets are "stackable" and are sent as a compound packet that con 
tains at least two packets, a report packet and a source desLptior 

All participants in a session send RTCP packets. A participant that has 
recently sent data packets issues a sender report The sender report (SR) 
contains the total number of packets and bytes sent as well as Lormanon 
that can be used to synchronize media streams from different sessions. 

Session participants periodically issue receiver reports for all of the sources 
from which they are receiving data packets. A receiver report (RR) con- 
tains information about the number of packets lost, the highest sequence 
number received, and a timestamp that can be used to estimate the round- 
tnp delay between a sender and the receiver. 

The first packet in a compound RTCP packet has to be a report packet 
even if no data has been sent or received— in which case, an empty ' 
receiver report is sent. J 

All compound RTCP packets must include a source description (SDES) 
element that contains the canonical name (CNAME) that identifies the 
source. Additional information might be included in the source descrip- 
tion, such as the source's name, email address, phone number, geographic 
location, application name, or a message describing the current state of the 
source. 



When a source is no longer active, it sends an RTCP BYE packet The BYE 
notice can include the reason that the source is leaving the session. 

RTCP APP packets provide a mechanism for applications to define and 
send custom information via the RTP control port. 



RTP Applications 



RTP applications are often divided into those that need to be able to 
receive data from the network (RTP Clients) and those that need to be able 
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to fransmit data across die network (KIP Servers). Some applications do 

a^tl T^u conferendn S applications capture and^m^ala 
at the same time that they're receiving data from the network. 

Receiving Media Streams From the Network 

• Conferencing applications need to be able to receive a media stream 
from an RIP session and render it on the console. 

• A telephone answering machine application needs to be able to 
receive a media stream from an RTP session and store it in a file. 

• An application that records a conversation or conference must be able 
to receive a media stream from an RTP session and both render it on 
the console and store it in a file. 

Transmitting Media Streams Across the Network 

RTP server applications transmit captured or stored media streams across 
the network. 

For example, in a conferencing application, a media stream might be cap- 
tured from a video camera and sent out on one or more RTP sessions The 
media streams might be encoded in multiple media formats and sent out 
on several RTP sessions for conferencing with heterogeneous receivers 
Multiparty conferencing could be implemented without IP multicast bv 
using multiple unicast RTP sessions. 



References 

The RTP specification is a product of the Audio Video Transport (AVT) 
working group of the Internet Engineering Task Force (IETF). For addi- 
tional information about the IETF, see http : //www. i etf . org. The AVT 
working group charter and proceedings are available at 
http : //www . i etf . org/html . charters/avt-charter . html . 

IETF RFC 1889, RTP: A Transport Protocol for Real Time Applications 
Current revision: http://www.ietf .org. internet-drafts/draft-ietf- 
avt- rtp-new-04 . txt 
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Current revision: http://www. ietf.org. internet-drafts/draft-ietf- 
avt-profile-new-06.txt 

™2f Z^ 100 T^ergoing revisions in preparation for advance- 
ment from Proposed Standard to Draft Standard arid the URLs listed here 
arefor the Internet Drafts of the revisions available at the tim^Sp^. 

Jn addition to these RFCs, separate payload specification documents 
™ ow particular payloads are to be carried in RTP. For a list of all of 
the RTP-related specifications, see the AVT working group charter at 
http : //www . i etf. org/html . charters/avt-charter . html . 



Understanding the JMF 

RTP API 



JMF enables the playback and transmission of RTP streams through the 
APIs defined in the javax.media. rtp, javax.media. rtp.event, and 

i 3 ^^ 1 a ' Pt P; T P P acka 8 es - JMF can be extended to support addi- 
tional RTP-speafic formats and dynamic payloads through ^standard 
JMF plug-m mechanism. 

n^Ji^^^ 1 ™P le «entations axe not required to support the 
RTF APIs in javax.media.rtp, javax.media. rtp.event, and 
javax.Bedia. rtp. rtcp. The reference implementations of JMF provided bv 
Sun Microsystems, Inc. and IBM Corporation fully support these APIs. 

You can play incoming RTP streams locally save them to a file, or both. 



Figure 8-1: RTP reception. 



For example, the RTP APIs could be used to implement a telephony appli- 
cation that answers calls and records messages like an answering machine. 

Similarly, you can use the RTP APIs to transmit captured or stored media 
streams across the network. Outgoing RTP streams can originate from a 
file or a capture device. The outgoing streams can also be played locally 
saved to a file, or both. J ' 
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Figure 8-2: RTP transmission. 

For example, you could implement a video conferencing application that 

separate RIP session for each media type. 5 

Smilarly, you might record a conference for later broadcast or use a prere- 
corded audio stream as "hold music" in a conferencing application. 

RTP Architecture 

The > JMF RTP APIs are designed to work seamlessly with the capture pre- 
sentation, and processing capabilities of JMF. Players and processors are 
used to present and manipulate RIP media streams just like any other 
media content. You can transmit media streams that have been captured 
from a local capture device using a capture DataSource or mat have been 

S ?J 6 t0 3 S^" 8 3 DataSi nk - SimiIar ^ JMF can be extended to support 
additional RIP formats and payloads through the standard plug-in mech- 
anism. ° 




Depacketizer Packe:izer 
Codecs ' Codecs 



Figure 8-3: High-level JMF RTP architecture. 
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Session Manager 

In JMF, a Sessi onManager is used to coordinate an RIP session The session 

The session manager maintains the state of the session as viewed from the 
local participant. In effect, a session manager is a local representa^f 

KTCP control channel, and supports RTCP for both senders and receivers. 
The SessionManager interface defines methods that enable an application 

™Tf?T d St V » * remove WMdSSEi 

created by the application, and close the entire session. 

Session Statistics 

The session manager maintains statistics on all of the KIP and RTCP nack 
ets sent and received in the session. Statistics are tracked for the entire ses- 
sion on a per-stream basis. The session manager provides access to global 
reception and transmission statistics: 

• GlobalReceptionStats: Maintains global reception statistics for the 
session. 

• ClobalTransmissionStats: Maintains cumulative transmission statis- 
tics for all local senders. 

Statistics for a particular recipient or outgoing stream are available from 
the stream: 

• ReceptionStats: Maintains source reception statistics for an individu- 
al participant. 

• TransnrissionStats: Maintains transmission statistics for an individual 
send stream. 

Session Participants 

The session manager keeps track of all of the participants in a session 
Each participant is represented by an instance of a class that implements 
the Part! ci pant interface. Sessi onManagers create a Participant when- 
ever an RTCP packet arrives that contains a source description (SDES) 
with a canonical name(CNAME) that has not been seen before in the session 
(or has timed-out since its last use). Participants can be passive (sending 
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There is exactly one local participant that represents the local client/server 
participant. A local participant indicates that it will begin leSw iScF 
control messages or data and maintain state on facom^EuS SSol 
messages by starting a session. 5 ana control 

A participant can own more than one stream, each of which is identified 
b^synchroruzation source identifier (SSRC) used by the source of Ae 

Session Streams 

The SessionManager maintains an RTPStream object for each stream of KIP 
data packets in the session. There are two types of RTP streams: 

• SendSt ream represents a stream of data coming from the Processor or 
input DataSource that is being sent over the network. 

i ReC JT± tream * COnStructed automatically whenever the session man- 
a^r detects a new source of RTP data. To create a new SendStream, ™ 
call the SessionManager createSendStream method. 

RTP Events 

Several RTP-specific events are defined in javax.media. rtp.event These 
events are used to report on the state of the RTP session and streams. 
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Figure &4: RTP events. 

To receive notification of RTP events, you implement the appropriate RTP 
listener and register it with the session manager: 

• SessionListener: Receives notification of changes in the state of the 
session. 



122 

JMF API Guide 

• ReaoteListener: Receives notification of events or RTP control mes 
sages received from a remote participant control mes- 

Session Listener 

You can implement SessionListener to receive notification about events 

There are two types of session-wide events: 

• Son t1C1Pa,,tEVent: ** 3 n6W P-rfrfP"* has Fined the 

• L*cal Col 1 isionEvent: Indicates that the participant's synchronization 
source is already in use. 

Send Stream Listener 

You can implement SendStreamLi stener to receive notification whenever: 

• New send streams are created by the local participant. 

• The transfer of data from the DataSource used to create the send 
stream has started or stopped. 

• The send stream's format or payload changes. 

There are five types of events associated with a SendSt ream: 

• NeaSendStreanEvent: Indicates that a new send stream has been creat- 
ed by the local participant. 

• ActiveSendStreamEvent: Indicates that the transfer of data from the 
DataSource used to create the send stream has started. 

• Inacti veSendStreamEvent: Indicates that the transfer of data from the 
DataSource used to create the send stream has stopped. 

• UKralPayloadChangeEvent: Indicates that the stream's format or pay- 
load has changed. 3 
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• StreamClosedEvent: Indicates that the stream has been closed. 
Receive Stream Listener 

You can implement ReceiveStreanUstener to receive notification when- 



ever: 

• New receive streams are created. 

• The transfer of data starts or stops. 

• The data transfer times out. 

• A previously orphaned ReceiveSt ream has been associated with a Par- 
ti ci pant. 

• An RTCPAPP packet is received. 

• The receive stream's format or payload changes. 

You can also use this interface to get a handle on the stream and access the 
Kir DataSource so that you can create a Medi aHandler. 

There are seven types of events associated with a Recei veStream: 

• NewRecei veStreamEvent: Indicates that the session manager has creat- 
ed a new receive stream for a newly-detected source. 

• Acti veReceiveStreamEvent : Indicates that the transfer of data has 
started. 

• InactiveReceiveStreanEvent: Indicates that the transfer of data has 
stopped. 

• TimeoutEvent: Indicates that the data transfer has timed out. 

• RemotePayloadChangeEvent: Indicates that the format or payload of the 
receive stream has changed. 

• StreanMappedEvent: Indicates that a previously orphaned receive 
stream has been associated with a participant. 

• Appl icationEvent: Indicates that an RTCP APP packet has been 
received. 



Remote Listener 

You can implement RemoteLi stener to receive notification of events or 
RTP control messages received from a remote participants. You might 
want to implement RemoteLi stener in an application used to monitor the 
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each s™ CePb ° n With ° Ut ^ t0 reCd VC data 0r ^onnation o7 

There are three types of events associated with a remote participant 
" recdved RePOrtEVent: Mcate8 ** an RTP teCeiver re P° rt has **** 
" a hfed ReP ° rtEVent: IndicateS *■* 311 RTP "nder report has been re- 



• RemoteOollisionEvent: Indicates that two remote participants 
using the same synchronization source ID (SSRC). 



are 



RTP Data 



The streams within an RTP session are represented by RTPStream objects 
There are two types of RTPStreams: Recei veStream and SendStream. Each' 
Kfl stream has a buffer data source associated with it. For Recei veS- 
treams, this DataSource is always a PushBufferDataSource. 

The session manager automatically constructs new receive streams as it 
detects additional streams arriving from remote participants. You con- 
struct new send streams by calling createSendStream on the session man- 
ager. 



Data Handlers 

The JMF RTP APIs are designed to be transport-protocol independent A 
custom RTP data handler can be created to enable JMF to work over a spe- 
cific transport protocol. The data handler is a DataSource that can be used 
as the media source for a PI aver. 

The abstract class RTPPushDataSource defines the basic elements of a JMF 
RTP data handler. A data handler has both an input data stream (Push- 
SourceStream) and an output data stream (OuputDataStream). A data han- 
dler can be used for either the data channel or the control channel of an 
RTP session. If it is used for the data channel, the data handler implements 
the DataChannel interface. 

An RTPSocket is an RTPPushDataSource has both a data and control chan- 
nel. Each, channel has an input and output stream to stream data to and 
from the underlying network. An RTPSocket can export RTPControl s to 
add dynamic payload information to the session manager. 
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f CaUSC ^ « RTP l° Cket Can * USed t0 construct a P1 ***r through the 
Manager, JMF defines the name and location for custom RTPSocket imp£ 

mentations: 

<protocol package-prefix>.media.protocol .rtpraw.DataSource 
RTP Data Formats 

AU ^-specific data uses an RTP-spedfic format encoding as defined in 

1 ^ IT T ^ deoFormat dass <*- For example, gsm RTP encapsu- 
lated packets have the encoding set to Audi oFormat . GSNLRTP, while jpee- 
encoded video formats have the encoding set to Vi deoFormat. 3 PEG_RTP. 

Audi oFormat defines four standard RTP-specific encoding strings: 

public static final String ULAW_RTP = "3AUDI0_C711_UUW/rtp"- 
public static final String Dvl_RTP = "dvi/rtp"; ' 
public static final String C723_RTP = "g723/rtp"; 
public static final String CSM_RTP = "gsm/rtp"; 

Vi deoFormat defines three standard RTP-specific encoding strings: 

public static final String JPEG_RTP = "jpeg/rtp"; 
public static final String H26X_RTP = "h261/rtp"; 
public static final String H263_RTP = "h263/rtp"; 

RTP Controls 

The RTP API defines one RTP-specific control, RTPControl. RTPControl is 
typically implemented by RTP-specific DataSources. It provides a mecha- 
nism to add a mapping between a dynamic payload and a Format. RTPCon- 
trol also provides methods for accessing session statistics and getting the 
current payload Format. 

SessionManager also extends the Controls interface, enabling a session 
manager to export additional Controls through the getControl and get- 
Control s methods. For example, the session manager can export a Buffer- 
Control to enable you to specify the buffer length and threshold. 



Reception 

The presentation of an incoming RTP stream is handled by a PI ayer. To 
receive and present a single stream from an RTP session, you can use a 
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MediaLocator that describes the session to construct a Player Amedia 
locator for an KIP session is of the form: 

rtp : //address : port [ : ss rc]/conten t- type/ [ttl ] 
Hie Player is constructed and connected to the first stream in the session. 
If there are multiple streams in the session that you want to present vou 
need to use a session manager. You can receive notification from the S 
s^n manager whenever a stream is added to the session and 2*Z7 a 
Player for each new stream. Using a session manager also enables you to 
directly monitor and control the session. ««esyouto 

Transmission 

A session manager can also be used to initialize and control a session so 
that you can stream data across the network. The data to be streamed is 
acquired from a Processor. 

For example, to create a send stream to transmit data from a live capture 
source, you would: * 

1. Create, initialize, and start a SessionManager for the session. 

2. Construct a Processor using the appropriate capture DataSource. 

3. Set the output format of the Processor to an RTP-specific format An 
appropriate RTP packetizer codec must be available for the data format 
you want to transmit. 

4. Retrieve the output DataSource from the Processor. 

5. Call createSendStream on the session manager and pass in the Data- 
Source. 

You control the transmission through the SendStream start and stoo 
methods. 

When it is first started, the SessionManager behaves as a receiver (sends 
out I?TCP receiver reports). As soon as a SendStream is created, it begins to 
send out RTCP sender reports and behaves as a sender host as long as one 
or more send streams exist. If all SendStrearns are closed (not just stopped) 
the session manager reverts to being a passive receiver. ' 
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Extensibility 

e^ed^e^l^ ^ R1P u ca P abaities °» be enhanced and 

J^r^T ^ h 8appM 3 basic ** of format s and payloads 
Advanced developers and technology providers can implement^ 
plug-ins to support dynamic payloads and additional RTP formatT 

Implementing Custom Packetizers and Depacketizers 

^mplement a custom packetizer or depacketizer, you implement the 
JMF Codec interface. (For general information about JMF P W-ins see 
Implementing JMF Plug-Ins" on page 85.) P g 
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Receiving and Presenting 
RTP Media Streams 



JMF Players and Processors provide the presentation, capture, and data 
conversionmechanismsforRTPstreams. pture, ana data 




Figure 9-1: RTP reception data flow. 

A separate player is used for each stream received by the session manager 
You construct a PI ayer for an RIP stream through the standard ManTgef 
createPl ayer mechanism. You can either 

• Use a Medi aLocator that has the parameters of the RTP session and 
construct a PI ayer by calling Manager . createPl ayer (Medi aLocator) 

• Construct a Player for a particular ReceiveStream by retrieving the 
DataSource from the stream and passing it to Manager . createPlay- 
er(DataSource). 

t«w r edl 'l L0 S at a 0r t0 COnStmCt 3 P1 ayer ' y° u onJ y P«w* the 

detected in ** 8e88ton - u y° u want to pW ba <* 

multiple RTP streams m a session, you need to use the SessionManager 
directly and construct a Player for each ReceiveStream. 
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Creating a Player for an RTP Session 

When you use a MediaLocator to construct a P1 ayer for an RTP session 
Ae Manager creates a Player for the first stream detected^ Ae sSon 

& ^ 3 R6al 1 26C0mpl e ~ « <- has beenTS in 

By listening for the RealizeCompleteEvent vou can Hp**™™ i. a. 
no, any daU has arrived and if 'the PUyer is^ °' 

ateRealizedPlayer to construct a Mayer for Z^le^S No 
Mayer would be returned until data arrives and if no data is detected at 
tempting to create a Realized P 1a yer would block indefSy 

A PI ayer can export one RTP-speciflc control, RTPControl, which provides 
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Listening for Format Changes 

^n^ Player P ° St l 3 FormatCh ^eEvent f it might indicate that a payload 
change has occurred. Players constructed with a Medi aLocator a U ?Z*H 
caUyprocesspayload change, Inmc>stcases, this pro 

present RTP media streams need to listen for FormatChangeEvents so that 
they can respond if a new Player is created. events so that 



When a FormatChangeEvent is posted, check whether or not the Playe 
object s ^control and visual components have changed. If they have, a new 

Player object's components and get the new Player object's components. 
Example 9-2: Listening for RTP format changes (1 of 2) 



r 

new 




Example9-2: Listening for RTP format changes (2of2) 
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Creating an RTP Player for Each New Receive Stream 

To play all of the Recei veStreams in a session, you need to create a sepa- 
rate PI aye r for each stream. When a new stream is created, the session 
manager posts a NewReceiveStreamEvent. Generally you register as a 
Recei veStreamListener and construct a Player for each new Recei veS- 
tream. To construct the Player, you retrieve the DataSource from the 
Recei veStream and pass it to Manager. createPlayer. 

To create a PI ayer for each new receive stream in a session: 
1. Set up the RTP session: 

a. Create a SessionManager. For example, construct an instance of 
com. sun. media, rtp. RTPSessionMgr. (RTPSessionMgr is an imple- 
mentation of SessionManager provided with the JMF reference 
implementation.) 
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c.^^ KIPsessionbycaIitagRTpsessio ^ r 
4 $tart * e 1 * «TPS e ss lonBgr startSess1o , 

mnlo Q_Q. C^uj 
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In your Recei veStreamListener update method, watch for NewRe- 
cei veStreamEvent, which indicates that a new data stream has been de- 
tected. 



J. When a NewRecei veStreamEvent is detected, retrieve the Recei veStream 
from the NewRecei veStreamEvent by calling getRecei veStream. 

i Retrieve the RIP DataSource from the Recei veStream by calling get- 
DataSource. This is a PushBuffer DataSource with an RTP-spedfic For- 
mat. For example, the encoding for a DVI audio player will be DVI_RTP. 

. Pass the DataSource to Manager . createPl ayer to construct a PI ayer. For 
the PI ayer to be successfully constructed, the necessary plug-ins for de- 
coding and depacketizing the RTP-formatted data must be available. 
(For more information, see "Creating Custom Packetizers and Depack- 
etizers" on page 167). 
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See RTPUti 1 in "RTPUtil" on page 223 for a complete example. 
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1-1 What is an application? 



An application in the context of Wph<*nh*«> ,v 

resources. Some examp.es o^ ^TSS^'S^ ° f USer - su PP'^ 
JavaServer Pages (JSP) static mi? oh i! ' Enter P r,se J ^a beans (EJB), 
wor;, static HTML, object groups and URLs 

- Oependencies over the entire 9^.^^^^ 

"eer. ^plications ^^T^nT^crr 68 * ^ 

contained by an, other re^silory o?j?a CannM be 

Tlie following section provides a brief overview m »,._-■ 

s a servlet? ~™ — 

maintenance aZZ^SZt^^^'"' minimal """""a. 

cwssKsssarSs 

on the server. Just the fea maTth. P "' ! " aro lte an Wlet runs 

advantage omr^^S^SSSZ T£T V b ' 9 

™*v,si W e^^^^^ 
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associated classes and mSZ^l^^ ^ 4 aton ° With the 
servers. Servlets can also use addTttonal^^ * m ° S ' major Web 
extend the Java Servlet API 2.1 C ' asSes and P^^ges to 

Servlets communicate through requests and 
behavior of HyperText Transfer pS SKI^ ! ° th6 
eng.ne running on a Web server bv usino7h7«L Y n,eract with a 
exampie, when a client ser^Z^TmeseZT^ F ° r 
request information onto the servlet and have the^, ^ Send the 
form a response which the server can teTs^ZlVTe^ ^ 



Internet Banking 
Front-End 



Websphere 
Server 




Request Account Balance 



_ HTML page wflh 

gg»|r Account Information 




Account Sen/tot 
Q« Account Wonrmtfon 



Account Swvfet 
R«um Account hfarmation 




*9ur e i. Example of servlet communication and interaction 

a servlet will continue to™ vSa for a dr£i' TT* 8 - Upon tein 9 toa **. 

ato^r^ 

compile the servlet code, any Jav^ t£m?P 2 c,ass To 
compiles without any errore and * . !? U8ed ' After the code 

these files into " ,e> then we nava «° copy 

the class file, ^m^lZTe^S^J^ code and 

need to go in »e rign, »£ZSZ^ *~ *• 

.2.1 Servlet lifecycle 
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handle requcs ,s hom zem or ^ ^ unlil ^ ^ Mrver remores ^ 
1.2.1.1 Initializing a servlet 

SSSeS3sS»r=r 

1-2.1.2 Handling client requests 
1.2.1.3 Destroying a servlet 
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1.2.2 Java Servlet API V2.1 overview 

1. An HTTP-specific package 

2. A non-HTTP-specific package 

• javax.servlet 

• javax.servlet.http 

These two packages contain seven interfaces five classes anri 

1.2.3 IBM extensions to the Servlet API V2.1 

In its attempt to make it easier to manage session states and to ™ a » a 

V2. 1 . The additional packages and classes are: 

• ^ibm.websphere.serviet.personalization.sessiontracking package 

• ^•'bm.websphere.servlet.personalization.userprofile package 

• com.ibm.websphere.db package 

• com.ibm.websphere.servlet.error.ServletErrorReport class 

• com.ibm.websphere.servlet.event package 

• com.ibm.websphere.servlet.filter package 

• com.ibm.websphere.servlet.request package 

• com.ibm.websphere.serviet.response package 



4 



Solution Guide Enterprise Edition: Getting Started 



1.2.4 Servlet API V2.1 details 

I" 15 ,*??™ describes th e functions of the Java Servlet API wi a „ 
the IBM extensions to the API. 2 1 as weH as 

As listed in 1.2.3, "IBM extensions to the Servlet API V2 r on na „ a „ .u 

wet w aM ^ are ^ r^craVsf * 

co mJ b m .web,phe re . S er, l ^ MM „^ lon ^„ twWn9p>c| ^ e 

This package provides the following: 

• Records the referral page that led the visitor to your Web site 

• Tracks the visitor's position within the site. 

• Associates user identification with the session. 

com.lbm.websphere.servletpersona.lzatlon.userpiofHep 

This package provides the following- 

your visitors. personalized experience for each of 

com.ibm.websphere.db package 

This package provides the following: 
• Simplifies access to relational databases 

com.lbm.websphere.servlet.enw^MetEnwR.poit class 

£5. SSTSST" 10 pravWe — detelw « — 

com.lbm.websphere.servlet.event package 

This package provides the following: 
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• An interface for registering listeners. 
com.ibm.websphere.serv/et.fllter package 
This package provides the following: 

• Support for servlet chaining. 

' zsssEZzsr* * ■» — - « - «. i. 

• The ServfetChain object. 

• The ChainResponse object. 

com.lbm.websphere.serv«et.request package 

This package provides the following: 

• The HttpServletRequestProxy abstract class is used to overload the 

com.ibm.websphere.servlet.response package 

This package provides the following- 

• The. ServlaOutpulstnamMapter class Is used lo convert an 

.2.5 Changes to packages supported in WAS V2 

- open data serv^cCs to Zc™ SSK£ """ir'" 6 ' 1 * P °°' 
allowed .he ser»te. to communicate di^d"w°™he daTsf™, 



APW0.««, in, SoWo„ 0u » B«„^ Efc Set*, sm« 



"mo^eT APP ' iCa,i0n Se,Ver Verelon 3 *• e— have b eK1 

• com.ibm.servlet.personalization.sam 

• com.ibm.serviet.servlets.personalization.util 

1.3 What are Enterprise Java beans (EJB)? " 

Webi?^^^ J - «-« (^Bs) in the context of 

to write EJBs For «£? ?hf « f 1 pr0V,de a detai,ed Ascription of how 

http=//w W . ito . c ^ soft ^ / ^^ ra/ai ^ / ^ r ^ ^ 

3.1 Introduction 

EJB components are lightweight, modular and eas? to dap* ^b!c^ S 
JavaBeans specifications which can be found at: surprise 

http: //java.sun. com/products/ejb/docs.htaal 

£££ r mai " Ca ' e0OrleS <* en,e,PrlSe bMns - - l» B9» 
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Figure 2, Categories of enterprise beans 



1.3.1.1 Entity beans 

(BMP). On the other hand when the container handles the data 
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Figure 3. Entity bean life cycle 

Each entity bean consists of the following 4 components: 
a. Bean Class: This class is implemented by the developer to encaosui^ 
the bus,ness methods and data. This class is hidden'™ fhe SL 
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co n n d 4e C r CeSSed * ** ^ im P le ™nted by the 

d. Primary Key Class: Since entity bean instances are unions thic „i M 
1.3.1.2 Session beans 

persistent by using underlying entity beans. * data 

Every session bean has the following three components: 

• Bean class 

• Home interface 

• Remote interface 

semi-penn^n, dan .he. ^stances ZTST^ 

across the methods and is shortTe* d0eS n ° l maintain data 
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For Transactional imrocMkmi, tht ccntinv mwka> ti» a 
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Figure4. Session bean life cycle 
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1.3.2 EJB architecture in brief 

1. EJB server 

the remote interface implemented by the container tL ah I 9 ? 9 
o, WebSphere ships with on, y one «T^?^^^^*g 

S2S£r enMy beans ' and the session container to 

»a?er can find detailed information on EJB servers in Writina 
WeZZe vT''" W6bSPhere ' SC09 - 4431 "01. that ships 
This book can also be viewed or downloaded from: 

2. Data source 

The persistent data in the entity beans is stored in a recoverable data 
source. For container managed persistence (CMP) the EJB^arvwSn 
supports IBM DB2, Oracle, and Microsoft SQL W IndttTSS 
(CB) supports DB2, Oracle, IBM CICS and IBM IMS? " 
For bean managed persistence (BMP), the user can use any data source 

c^e fo r ir bP ° S, °: e J" , P f rS, ' Stent da,a " The user w '» tnenVave ^ w S 
code for the beans to handle their own data source interactions 

3. EJB clients 
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The EJB clients can be one or more of the following: Java servlet Java 
app let-servlet combination, or a JSP file. A Java applet M n be used wfth a 
se vlet to interact with the enterprise beans, while in the EJbWTcB) 
JsZTTrT direCt,y int6raCt wi,h the Enter P ri ^ Java befn^Tn an } ' 

n£»* ?°" BA ; bas ^ ^a clients, and to a limited degree a C++ 
CORBA clients. More details on how to write EJB clients ran ha «IL * 

Administration interface 

liminf S T% (A S E) US6S the WebS P her e Administrative Console to 
admm.ster the EJB server. The EJB server (CB) uses the System 
Management End User Interface (SMEUI) 




Figur*5. EJB environment and interaction with other components 



1.4 What are JavaServer Pages (JSP) 

JavaServer Pages (JSP) technology provides developers with an easy and 
generate HTML, eXtens.ble Markup Language (XML), and other structured 
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1.4.1 JSP process flow 

The JSP process How is shown in Figure 6 on page 15. 
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Figure 6. JSP process flow 



When WebSphere is installed on top of a Web server, the Web server's 
conf.gurat.on is modified to pass the HTTP requests for the JSP filet to the 
2?SSl aPI- !? , !? , S6rVer - WebS P here th *n passes this requesUo tt 

and?n £f ? h,Ch ' S n0lhin9 bUt 3 Java servlet wnich ^PiS the JSP file 
and in the process creates two files for each JSP file. It creates a iava mJ 
whrch has the Java code for the servlet, and a xlass file Si » XJIh 
bytecode for the Java file. The JSP Processor for TsP C J.'gTis fhe P 

com.ibm.servlet.jsp.http.pagecompile.PageCompileServlet 
and for JSP 1.0 it is the 

com.sun.jsp.runtimeJspServlet 
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ShlrThf TfT PU !t the jaVa and tne c,ass ™« '"side the 

\WebSphere\AppServer\Temp folder. The location of these files win 

on whether you are using JSP 0.91 or JSP 1.0 ™wZ!cZ«on ? ~" 

For example, if you are using JSP 0.91 and the JSP file is in the following 

n.!!^ S ,K^ "»n the JSP processor will 

place the .java and the .class files in the following path: processor Wl11 

<WASRoot>\temp\examples\pagecompile folder. 

P ZT fWi " ? 3me ,h6 java and the c,ass files « X ^ip C and 
-S.mp.e_xjsp.Cass, respectively. Under JSP 0.91 the^jav^t f aiw^s kept. 

If you are using JSP 1 .0 and the JSP file is in the following folder: 

th *n the JSP processor will 
place the .class files in the following path: processor will 

<WASRoot>\temp\examples 

The JSP i.o processor names the .class file simple.class and by default th* 
seune^ 

set the Init Parm Name teepgenerated used by the JspServlet to vZ. 
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Ftgure7. Setting InitParm Name for JspServtet 



The Java and the .class files generated from the JSP file are servlets 
extending the javax.servlet.http.HttpServlet class. A sample JSP 0.91 file and 
the Java code generated by it is shown in Figure 8 on page 18. 

<BEAN naroe= " sirTpleSessianMsg" type= " SimpleJSFBean n create^ true" 
scope= " session" >< /BEAN> 

<BEfflN nane="sirrpleRequestMsg" type= " SirnpleJSPBean " create- "true" 

scopes " request " >< /HEAN> 

<% 

SirapleJSPBean simpleApplicationMsg = 
(SirqpleJSPBean) 

getServletOantext ( ) .getJVttribute( w sinple^jplicatianMsg") ; 
%> 

<htral> 

<head><title>Siniple JSP</titlex/head> 
<tocry> 
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<img src-banner.gif - alt= "banner image- height=aoo width=584xp> 

<hl>Simple JSP page</hl> 

<% if (sinpleApplicatianMsg 1= null) { %> 

^Application Bean:</B> <%=sinpleflpplicatianM S g.getMe SS age() %><br> 

<B>Sessian Bean:</B> <%= sinpleSessionMag.getMessagef) %> <BR> 
<B>Request Bean:</B> <%= sinpleReguestMsg.getMessageO %> <BR> 

</body> 
</html> 



Figure 8. simple. JSP code 0.91 

When this file is processed by the JSP processor, the _simple_xjsp.java file is 
generated. In Figure 9 on page 1 9, only a snippet of code is shown Please 
refer to Appendix B, 'Sample Code" on page 549, for all of the code and an 
example of the code generated by the JSP 1.0 compiler. 

package pagecorapile; 

import java.io.*; 
inport java.util.*; 
import javax.servlet.*; 
import javax.servlet .http.*; 
import java. beans. Beans ; 

import con . ibra . servlet . j sp . ht tp . pagecorapile . ParamsHttpServletJRequest ; 
import com . ibra . servlet . j sp . http . pagecorapile . ServletUtil ,- 
import com . ita . servlet . j sp . ht tp . pagecorapile . f ilecache . CharFileDa ta ; 
import com.ita.servlet.jsp.htt^.pageccnpile.NCSAUtil; 

import SirtpleJSPBean; 

public class _simple_xjsp extends javax.servlet. http. HttpServlet { 
private static final String sources [] = new String [] { 

"c : \\websphere\\appserver\\hosts\\default_host\\exanples 
*reb\\simple. jsp", 

}; 

private static final long lastModif ied [] = { 
926708647000L, 

b 

public void service (HttpServletRequest request, 
HttpServletRespanse response) 
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throws IOException, ServletException 



} 

SimpleJSPBean sinpleSessionMsg= (SinpleJSPBean) 
request. getAttribute("sinpleSessicnMsg n ) ; 
if ( sinqpleSessionMsg == null ) 

throw new ServletException ( n Invalid BERN name: 
siIllpleSessionMsg ,, ) • 

{ 

java.util. Properties p = new java.util. Properties*) ; 
java.util. Efcuraeration e = request. getParameterNaraes '() ; 
while (e . hasMoreElements ( ) ) { 

String name = (String) e.nextElenent () ; 

p. put (name, request. getPararaeter (name) ) ; 

com. ita. servlet .utU .Beansutil . setProperties (siitpleSessionMsg, p) ; 



} 

Figure 9. Code snippet of the _simple_xjspjava file generated by the JSP processor 

1.4.2 JSPIifecycle 

Since after compilation, JSPs generate a servlet, their life cycle is similar to 
that of a servlet. When the ServletEngine receives a request for a JSP file it 
checks to see if the servlet already exists or if the JSP file has changed since 
the last time it was invoked. If the servlet for the JSP does not exist in the 
application classpath or if the JSP file was changed since the last time it was 
loaded, the servlet engine passes the request to the JSP processor (or the 
pagecompile servlet). This creates another Java and .class file for the 
requested JSP file. These files are placed in the application classpath. The 
servletengine then creates an instance of the class file and calls the servlet 
serviceO method in response to the request. Once the .class and Java files 
have been created by the JSP processor, all the subsequent requests for the 
JSP servlet are handled by the instance of the servlet that was created by the 
servletengine. By default, the JSP syntax in a JSP file is converted to Java 
code by the processor and this code is placed in the service() method of the 
generated class file. This default behavior can be overridden by using the 
method directive in the JSP file. 

The JSP servlet is terminated when the servletengine no longer needs the 
servlet or a new instance of the servlet is being loaded by the servletengine. 
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In doing so, the destroy*) method in the servlet is called. If there is a need to 
conserve resources or if the previous request to the servlet times out then 
also, the servletengine can call the destroy() method of the servlet. 
1.4.3 JSP access models 

When using JSPs there are commonly two types of access models used: 

1 . JSP file handles both the request and the response 

In this model the JSP file handles both the request and the response to 
and from the client browser. The JSP passes the request to beans or other 
components to generate the dynamic content. The response is sent back 
to the JSP file from the beans, which in turn sends it back to the client 
browser. 

2. JSP handles response, servlet handles request 

In this model, the client request is sent to the servlet, which handles the 
dynamic content generation. It then calls a JSP file to send the response 
back to the client Using this model, one can effectively separate the 
business logic from the content display. 

These two JSP access models are discussed in more detail in the redbook 
Patterns for e-business:User to Business Patterns for Topology 1 and 2 usino 
WebSphere Advanced Edition, SG24-5864-00. 

1.4.4 JSP syntax 

In WebSphere V3, JSP conforms to the JavaServer Pages Specifications 
0.91 or 1.0 from Sun Microsystems. IBM has added some enhancements 
particularly in the area of database access. The Sun JSP 1.0 specification 
can be found at 

http : / / java .sun. com/products/ j sp/download . html 

A full discussion of JSP syntax including the differences between Version 
0.91 and 1.0, and details of the IBM extensions can be found in the redbook 
WebSphere Studio and Visual Age for Java Servlet and JSP Programmina 
SG24-5755-00 



1.5 Enterprise Java Server (EJS) Runtime 

The Enterprise Java Server (EJS) Runtime provides support for the 
Enterprise Java beans (EJB) programming model in which enterprise beans 
are managed by containers. Containers, in turn are executed within servers 
which are operating system processes that contain their own Java Virtual 
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Machine (JVM). Each JVM is managed by the System Management 
infrastructure of the application server. 



The SM infrastructure allows the execution environment to be defined, 
enabled and monitored. The execution environment is made up of beans 
containers and servers. 

For more detailed descriptions and examples on each of the EJS functions 
please refer to 2.1, "IBM WebSphere Application Server components" on 
page 31 . 

1.5.1 Enhancements to the IBM extensions required for the EJS 

The EJS programing model utilizes the RMI/IIOP model to provide distribution 
for the EJBs in standard and advanced releases of the EJS. The enterprise 
release of EJS requires the use of Interface Definition Language (IDL) to 
allow interoperability with the Component Broker (CB). 

Some of the existing IBM extensions in the IBM Java ORB have been 
re-implemented as an effort by the Component Broker team to enhance the 
JBroker Java ORB to support the EJS. Some of these features are briefly 
discussed below. 

1.5.1.1 Persistent Name Service (PNS) 

PNS is not an ORB feature but it is required to provide reference to the 
persistent objects. PNS implements CORBA CosNaming specification and 
this mechanism will be standardized for pluggable persistence. 

1.5.1.2 Object Resolver 

The Object Resolver provides a pluggable interface to allow an external class 
to act as a specialized object adapter. 

1.5.1.3 Request interceptor (Rl) 

The Rl allows access to the request header after marshalling out and before 
demarshalling in. This was done because the Request and Message 
Interceptor design from the original Sun ORB was not compatible with how 
C++ ORB handled interceptors. 

1.5.1.4 Property setting and getting flags 

Since the OMG defines only a couple of basic properties 

(org.oBog.OORaA.CRBClass, org.orag.a^RBA.CRBSingletonClass), they are not 

enough for IBM-specific properties. Support for these properties has been 
added and it will affect the method GRB.set^rameters and other affiliated 
methods. 
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1.5.1.5 JNDI support 

EJS implements the Java JNDI APIs to support the CORBA CosNaming. 

1.5.1.6 Java Transaction Service (JTS) 

JTS supports the ORB. This is done by implementing the Request 
Interceptors, which allows the JTS to be enabled by the ORB. 

1.5.1.7 Browser callbacks 

Normally, a client makes method calls to an object residing on the server. 
This is done when the server creates a listener socket and the client opens a 
port to that socket. By using the same listener socket, created by the server, 
and the port, opened by the client, functionality has been added for the server 
to make method calls to the object residing in the client. The roles have been 
essentially reversed. This is possible only in the case of signed applets. A 
similar capability has been added to the C++ ORB. 

1.5.2 New features in Java ORB required for the EJS 

Some of the new features in the IBM Java ORB, that are required by the EJS 
runtime have been briefly discussed below. 

1.5.2.1 Pluggable feature framework 

In WebSphere V3.0, special emphasis has been paid to providing a very 
pluggable component-based framework. This kind of framework will take care 
of problems arising from receiving frequent updates of the Java ORB from 
Sun Microsystems and it will meet the needs of different internal customers 
with varying requirements. This feature is meant for private use only by the 
ORB team 

1.5.2.2 Pluggable transport layer 

In order to support any environment, it is necessary to have a pluggable 
transport layer. EJS has a pluggable transport layer, which means that the 
socket creation will have to take place in this layer. Other ramifications are 
that the CDRInputStream and CDROutputStream will also have to be 
replaceable. 

1.5.2.3 SSL support 

Support for the SSL interface on the server side has been provided. Using the 
MIME encoded MOP allows browsers and Web servers to use SSL. By 
selecting to enable SSL, the user can force an SSL connection between the 
client and Web server for greater protection of the user ID and password data. 
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1.5.2.4 Mime-encoded HOP tunneling with HTTP 

HOP tunneling means sending HOP messages embedded in an HTTP 
request/response. When the client or a firewall does not allow a post method 
the mime encoded HOP tunneling technique can be used. This technique 
allows the mime encoded HOP to tunnel through an HTTP firewall or Web 
server as an HTTP message. 




Figure 10. Mime encoded HOP tunneling through a 3-tier framework 
1.5.2.5 HOP tunneling 

There are 2 types of HOP tunneling. In the first approach, multiple HOP 
messages are embedded in an HTTP request and are communicated to the 
ORB using sockets. This approach has some security implications on Web 
servers and will not be used. The second approach is to attach the HOP 
request to a single HTTP request as a parameter with binary data. This 
request reaches the ORB using the servlet that is started by the HTTP 
request. The response is then sent back as binary HOP data. This approach 
is used since it is more secure. 
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1.5.2.6 HOP firewall support 

SOCKS V5 is used to provide the HOP firewall support by providing 
authenticated connections. 

1.5.2.7 HOP redirector 

HOP redirector works in a similar fashion to the proxy firewall. It copies any 
replies/requests on a socket to a socket on which the ORB is connected. 

1.5.2.8 Configurable requests time-outs 

Only client-side timeouts have been implemented. This is done by throwing 
the NO_RESPONSE system exception on the client side with the completion 
status of maybe. The timeouts are set by using two ORB properties: 

1. com.ibm.CORBA.RequestTimeout 

2. com.ibm.CORBA.LocateRequestTimeout 

The default value for both of these timeouts is 0. A timeout value of 0 means 
an infinite timeout interval. 

1.5.2.9 eNetwork Dispatcher 

The eNetwork Dispatcher is a WebSphere HTTP sprayer used from Work 
Load Management (WLM). 

1.5.2.10 LDAP naming service 

EJS provides the LDAP naming service support indirectly through a JDBC 
layer implemented for CosNaming. As part of LDAP support, the EJS also 
supports the URL contexL 

1.5.2.1 1 Work Load Management support (WLM) 

WLM distributes the workload or requests across a server group. This 
functionality is supported in WebSphere V3. Smart proxies are used within 
the client along with a WLM runtime. 



1.6 Preparing for installation - What to change and why 

Before running the setup of WebSphere for version 3.0 it was necessary to 
make some of the following changes, to ensure a good install. These hints 
were documented in the WebSphere Readme file that shipped with the 
product 
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1.6.1 Set the JAVA.HOME environment variable 

Setting this variable allowed the OLT install to find the correct files as 
discussed in 4.3.0.2, 'Installing and configuring the OLT/OLD environment" 
on page 268. The 3.02 WebSphere install on NT completes successfully eve 
if the java_home variable is not set. 

For the Windows NT platform: 

1. Open the Control Panel. 

2. Double click the System icon. 

3. Select the Environment tab. 




Figure 1 1. The Windows NT System Properties Environment settings 

4. Type in JAVA_HOME in the variable field. 

5. Type in your JDK path, for example c:\jdki. i.7b in the value field. 

6. Click Set. 

7. Click OK. 
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FortheAlX Platform: 

1 . Log in as root or a super user. 

2. cd/etc 

3. Edit the environment file with an editor of choice, for example, vi. 

4. Add the line JAVA_HOME=/usr/jdk_has& 

5. Save the file and exit. Next time you log in the environment will be 
updated. Below is an example of our settings within the /etc/environment 

file: 



r ■ . — - 

^KtSdT 5111 :/GtC: /uSr/sbin : /"sr/iicb : /usr/bin/Xl l:/sbin 
LANG=en_US 

10CPATH=/usr/lUb/nls/loc 

ft 2£ w to deterraine which Ejects to operate oq 

£ i S '•■a***""*- " tMs is where the device dbjects 

#reside, which are required for hardware configuration 
CCMDHt=/etc/ob j repos 

# IMNSearch EBCS environment variables 
IMQCEaJFTGSRV=/etc/lMNSearch 

IMQCIMFr(XX=/etc/IMl^arch/dtahelo 

# Added by steen 
JAVAJKWB=/usr/ j dkjbase 

Figure 12. /etc/environment settings 



Increase the DB2 application heap size for the WAS database 

In order for the Admin Server to work correctly the application heap size must 
be changed from its default setting of 128 to a new value of 256. In the 3.02 
install on NT the installation will update this setting automatically for you This 
can be done manually either through the DB2 UDB Control Center or through 
the db2 command line interface, below are examples of both. 

From the DB2 UDB Control Center: 

1- Open the Control Center and expand the system that the WAS Database 
resides on, so you can see the WAS DB on your screen, as shown below 
in Figure 13 on page 27: 
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Figure 13. D&2 UDB Control Center - the WAS database 



2. Right-click the WAS database icon and select Configure. 
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Figure 14. Configure the WAS database 



3. Select the Performance tab. 

4. Scroll down the list of parameters and select Application heap size. 

5. Change the value from 128 to 256. 
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Figure 15. How to change the application heap size 

6. Click OK. 

7. Close the Control Center. 
From the command line: 

1 . Start up a DB2 Command Line window (NT) or ensure your 
~/sqllib/db2profile has been activated (AIX). 

2. Connect to the WAS database with a valid user ID and password: 
connect to was 

3. To update, type the following command: 

update db cfg for was using APPLHEAPSZ 256 

4. Disconnect all applications: 

force applications all 
termiriatG 

5. Then stop and start db2. 
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Chapter 2. WebSphere Application Server overview 



This chapter will give a high-level overview of the Enterprise Java Server 
functions as deployed in IBM WebSphere V 3.0. 

2.1 IBM WebSphere Application Server components 

WebSphere Enterprise edition ships with two different Enterprise Java 
Servers as discussed in 1.3.2, "EJB architecture in brief on page 12 The 
following is an overview of the main components in the EJS provided bv 
WebSphere Advanced Edition (AE) and a brief look at the main components 

° SiM . PrOV i ded by Com P° nent Broker < CB )- We also discuss the features 
of WebSphere Standard Edition because they are included in Advanced 
Edition and they provide the necessary foundation for Advanced Edition 
functions. 

2.1.1 Architecture overview 

This section gives an overview of the components in the general EJS 
architecture. 

Enterprise Java Services (EJS) refers to the infrastructure designed to run 
servlets and Enterprise Java beans. 

The EJS is based on Sun's Enterprise JavaBeans Technology specifications 
that specify an enterprise Java platform defined through a set of standard 
Java APIs that provide access to existing infrastructure services. 

2.1.1.1 EJS architecture 

An EJB server provides the following components: 

• The EJB server runtime 

The server runtime can be seen as a generic server (or model/template 
server) from which the Web application server instances can be modeled. 
EJBs live in containers that again live in the server runtime (Web 
application server) see Figure 18 on page 37. 

Servlets also live in a special container (servlet engine) that again live in 
the server runtime (Web application server) see Figure 17 on page 36. 

• The EJB containers 

EJB containers are provided following the requirements as described in 
the Enterprise JavaBeans specifications Version 1 .0 (for further 
information see http://java.sun.con/products/ejb/). Furthermore, IBM 
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provides additional features for example, entity bean support with bean 
managed or container managed persistency and a simple deployment 
tool. 

See 2.1.2, "Enterprise Java beans and containers" on page 39 for more 
details on containers and EJBs. 

• The Enterprise Java beans 

This combination of components provides a number of services. These are: 

• A deployment tool 

When an EJB has been developed it has to be transformed into a form that 
enables it to be managed and accessed. The transformation is referred to 
as EJB deployment. 

To deploy an EJB you will normally use a built-in tool of an IDE (Integrated 
Development Environment) or a stand alone tool. 

See 2.1.4, "Deployment tools" on page 40 for more details. 

• Naming services 

The IBM WebSphere Application server architecture provides naming and 
directory services to provide an interface to find EJBs based on the name 
or an attached attribute. 

In IBM WebSphere the Java Naming and Directory Interface (JNDI) is 
used to provide a common interface to the actual naming and directory 
service that is being used. 

JNDI provides an Application Program Interface (API) to be accessed 
through a Java application and a Service Provider Interface (SPI) to 
specify the interface to existing and widely used name and/or directory 
services. The purpose of providing an open SPI specification is to make 
the JNDI independent of the specific naming or directory service 
implementation used. 

For further information on the JNDI specifications see: 

http : // j ava . sun . can/products/ jndi/ 

For more details on naming and directory services see Chapter 7, 
"WebSphere access control and security" on page.363. 

• Security services 

The security services provide support for Web resources (for example, 
HTML, JSP and CGI files), sen/lets and EJBs. 

The security authorization information, authentication and delegation 
policies will typically be defined using the IBM WebSphere Administrative 
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Console. In WebSphere Advanced the security service is an EJB server 
that contains security beans. 

See Chapter 7, "WebSphere access control and security" on page 363 for 
more details on security. 

• Work Load Management 

A Work load management (WLM) mechanism is provided to make scaling 
of enterprise applications running on IBM WebSphere Application server 
possible. 

Workload Management is a service that improves the scalability of an EJB 
server runtime environment by grouping multiple servers together into a 
server group. EJB clients can access this server group as if it was a single 
server. The actual server that responds to the client request will be 
transparently determined by the Workload Management service. 
WebSphere implements a number of different policies for how the 
Workload Management service will choose the server. 

We do not cover Workload Management in this book. 

• A persistence service 

This service provides support for the proper interaction between a bean 
and its data source to ensure that any persistent data is maintained. 

In AE this is accomplished by using the JDBC API to interface with 
relational databases and Java transaction support. 

In CB the persistent service is accomplished using the X/Open XA 
interlace to relational databases and the OMG Object Transaction service. 

• A transaction service 

This service implements the transactional attributes specified in an EJB's 
deployment descriptor. 

• System management infrastructure 

The system management infrastructure enables management of Web 
server, Web application server and Web application resources. A client 
interface is provided for the administrator to manage these resources. 

An overview of the AE system management infrastructure is given in 2.1.5, 
"System Management Infrastructure* on page 40. 

The IBM WebSphere Administrative Console is provided with IBM 
WebSphere 3.0 Advanced. 

See 2.1.5.1, "Systems management console" on page 41. 
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The client interface for the EJB server (CB) environment is the systems 
management end user interface. We do not discuss this interface in this 
redbook. Please refer to the redbook WebSphere Application Server 
Enterprise Edition Component Broker 3.0 First Steps, SG242033 for more 
details. 



2.1.1.2 WebSphere Application Server Standard Edition 

The WebSphere Application Server Standard Edition provides a basic Web 
application server environment for Web applications that typically consist of 
HTML files, JSP files, applets, servlets, image files and databases. 

The primary purpose of the IBM WebSphere Application Servers is to provide 
an environment into which scalable, portable, well performing and reliable 
Web applications can be developed and executed based on Java-based 
programming, standard techniques, Internet standards, standard middleware 
and database management systems. 

IBM WebSphere Application Server Standard Edition provides an 
environment where you can extend and enhance your Web applications by 
migrating your HTML to JSP. Since JSPs essentially are HTML files with 
additional JSP-specific tags you can use your HTML skills and standard 
development tools. 

IBM WebSphere Application Server compiles the JSPs (at runtime) and 
transfers them into servlets. However, this process is managed by IBM 
WebSphere Application Server and is transparent to the developer. 

Since JSPs can include Java code and you write your servlets in Java you 
can use Java in your development - if you want to or the requirements force 
you to. However, you are not necessarily required to do so. 

Traditional" Web development components like CGI programs, Web Server 
APIs and client side scripting languages may also be utilized since an IBM 
Web Application Server setup includes a "traditional" Web server. 

IBM WebSphere Application Server Version 3 integrates with many different 
Web Servers and includes plug-ins for IBM HTTP Server, Apache, Lotus 
Domino Go V4.6.2.5, Lotus Domino, Netscape Enterprise Server, and 
Microsoft IIS. 

To integrate with a Web server you must select one or more of the plug-in 
extensions as shown in Figure 16 on page 35. 
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Figure 16. Web servers that integrate with the application server 

The application server provides the runtime environment for execution of 
servlets. See Figure 17 on page 36 for a view of this runtime architecture. 

The Web application server also provides a connection manager function that 
manages database connections. The connection manager provides an easy 
to use mechanism for reducing the resources required by Web applications 
when accessing databases. 

Furthermore, the Web application server provides transaction support 
through an implementation of Java Transaction Server (JTS) in relation with 
JDBC/XA databases. 

Finally, the IBM WebSphere Application Server Standard Edition architecture 
includes a system management infrastructure with two primary components 
the Administrative server and the Administrative client (console) (seeFigure 
17 on page 36). 

For further information on the system management structure see 2.1.5, 
"System Management Infrastructure" on page 40. 
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Figure 1 7. WebSphere Application Server Standard Edition 3.0 runtime architecture 



2.1.1.3 WebSphere Application Server Advanced Edition 

The WebSphere Application Server Advanced Edition (AE) has the functions 
found in the WebSphere Application Server Standard Edition plus support for 
EJBs and distributed (clustered) systems. This application server is one of 
two EJB servers provided in IBM WebSphere Enterprise Edition. 

Since IBM WebSphere Application Server Advanced Edition is an extension 
of the Standard Edition you can easily move an application developed for a 
server running Standard Edition to servers running Advanced Edition. 

The Web application server in IBM WebSphere Application Server Advanced 
Edition (see Figure 18 on page 37) includes support for EJB containers (for 
the EJBs) besides the servlet engine (for the servlets and JSPs) also found in 
Standard Edition. 
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Figure IB. WebSphere Application Server Advanced Edition 3.0 runtime architecture 

There is a single instance of the administrative server on a single node 
(physical machine). 

In a multi-node setup (cell) there will be a single instance of the administrative 
server on each node. The administrative servers contains identical 
configuration information and access the same configuration repository in the 
same database (see Figure 19 on page 38). 

The rationale is that you should be able to access any one of the 
administrative servers in a cell and see changes reflected on any other 
administrative server in the cell (single administrative image). 

The WebSphere administrative database can be located either on a separate 
database server (physical machine) or on one of the machines that host the 
administrative servers. However, each machine must have database server, 
client or connection software installed and configured to enable access to the 
common database. 
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If you plan to run the same Web applications and enterprise applications on 
more than one physical machine you will also have to ensure that all systems 
have access to identical (or the same) files and in identical locations in the 
directory structures. This can be accomplished either by creating identical 
files and directory structures on each machine or by using a shared file 
system. If the first method is used we would recommend that you establish an 
automatic or semi-automatic procedure to ensure that the data are identical. 
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Figure 19. WebSphere Application Server Advanced Edition multi-node setup 

A concept of server groups has been implemented in the IBM WebSphere 
Application Server for management and control purposes. 

The following applies to the server group concept: 

• Server groups consist of one or more Web application servers. 

• A single Web application server can only belong to one server group. 

• A server group can be seen as a logical server. 

• Web application servers within a group are clones of each other. Clones in 
this context means logically identical application servers with respect to 
configuration of resources for example, containers and EJBs. 
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• The Web application servers within a server group may be distributed to 
different nodes (physical machines). 

The server group is very useful in relation to workload management A 
request can be forwarded to a server group and the request is handled by a 
server in the group while the specific server identity is hidden from the 
requester. 

2.1.2 Enterprise Java beans and containers 

The IBM WebSphere Application Server Version 3.0 server architecture 
provides a generic server (the Web application server, see Figure 18 on Dade 
37) in which EJB containers live. 

One of the primary responsibilities of an EJB container is to provide a number 
of fundamental services for example, transaction, state, security and 
persistence to the EJB. The advantage being that it reduces the work 
required by the EJB developers and supports development of portable EJBs. 

Another responsibility of an EJB container is to create the interfaces (EJB 
Home and EJB Object) required for an EJB client to access a deployed EJB 
so the EJB client interacts indirectly with the EJB through the EJB container 




Figure 20. Client - EJB container relationship 



2.1.3 Servlets and the application server 

A special container (a servlet engine) is provided in IBM WebSphere 
Application Server to enable servlets to be run within the application server. 
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The servlet engine has been designed to be integrated as seamlessly as 
possible in the EJS architecture as well as in the security and system 
management infrastructure. The design approach allows for consistent 
system management for servlets and EJBs as appropriate while maintaining 
the typical servlet environment and characteristics intact. 

Servlets are created and managed as members of a Web application in IBM 
WebSphere Application Server Version 3.0. IBM WebSphere Application 
Server provides work load management support for servlets (as it does for 
EJBs) to allow requests for servlets within a server group to be distributed to 
application servers belonging to the group. 

2.1.4 Deployment tools 

When you have developed your Enterprise Java beans for example, using 
VisualAge for Java or manually they have to be deployed. 

When you deploy an EJB you create or modify a Jar file which includes a 
description of the Jar file contents (the manifest), deployment descriptors, 
bean class files and potentially environment properties. 

To create a deployed EJB Jar file you can for example, use VisualAge for 
Java, the Jetace tool or you can use the tools available in the Java 
Development Kit (JDK). The Jetace tool is provided as part of the IBM 
WebSphere Application Server. 

After the EJB Jar file has been deployed for your IBM WebSphere Application 
Server it must be installed in your environment in accordance with the 
WebSphere administrative infrastructure. IBM WebSphere Application Server 
Advanced Edition provides the WebSphere Advanced Administrative Console 
to be used for EJB creation (installation). 

Depending on the requirements for your EJB you may even choose to deploy 
an undeployed Jar file during EJB creation using the WebSphere Advanced 
Administrative Console. 

You will also find a command line tool wlmjar with WebSphere Application 
Server Advanced Edition that can be used to create a workload-managed 
prepared version of your Jar file. 

2.1.5 System Management Infrastructure 

This section describes the IBM WebSphere Application Server administration 
model. 
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2.1.5.1 Systems management console 

The WebSphere Administrative Console is the system management console 
for IBM WebSphere Application Server Version 3.0 Advanced Edition. 

An administrative domain (sometimes referred to as a cell or sphere,) is a 
collection of managed nodes, that is, host machines. Each managed node 
has an administration server executing on that node that is responsible for 
configuring, monitoring, and managing the WebSphere servers that run on 
that node. A client graphical user interface is provided to enable the 
administrative domain to be defined. 




Client Session Beanif||| 

Servlet i 1 

Figure 21. WebSphere Administration Server administration model 



This Graphical User Interface (GUI) makes it easy to interact with the beans 
that were loaded by the adminserver. The front-end has a tab look and feel 
and has three main tabs as shown in Figure 22 on page 42, Figure 23 on 
page 43, and Figure 24 on page 45. The WebSphere Administrative Console 
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has three tab panes namely Types, Topology, and Tasks. These three panes 
are discussed below. 



2.1.6 The Types view 

The Types view is a hierarchical view of all resources on all nodes in the 
administrative domain. Each folder icon represents a different resource type. 
By selecting any object and right clicking, a context-sensitive menu appears. 
This menu has the basic tasks such as Create, Move, Default Properties. 

The Types pane is shown in Figure 22 on page 42. 





Figure 22. WebSphere Advanced Administrative Console - Types tab 



2.1.7 The Topology view 

The Topology pane consists of the WebSphere Administrative Domain and all 
the managed nodes as shown in Figure 23 on page 43. For each managed 
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node there is an associated hierarchy of ail the resources within that node. 
The resource attributes can be changed and methods can be invoked on 
these resources in this view also, just as in the Types view. 
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Figure 23. WebSphere Advanced Administrative Console - Topology tab 
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2.1.8 The Tasks view 

The Tasks view shows different tasks that can be performed and is shown in 
Figure 24 on page 45. it consists of three task groups, which are briefiy 
discussed below. 

2.1.8.1 Configuration tasks 

This group of tasks allows you to configure application servers, virtual hosts, 
servlet engines, web Applications, and enterprise applications. 

2.1.8.2 Performance tasks 

This task allows the user to launch the Resource Analyzer tool to monitor 
performance and load statistics. The Resource Analzer is dicussed in more 
detail in the redbook WebSphere V3 Performance Tuning Guide 
SG24-5657-00. 

2.1.8.3 Security tasks 

Using this task, you can apply security to enterprise applications and to the 
HTTP and EJB methods of resources such as servlets and enterprise beans. 
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. ^WebSphere Advanced Administrative Console 




Figure 24. WebSphere Advanced Administrative Console - Tasks tab 
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8.1.6 Starting the LDAP directory server from the command line 

To start LDAP from the command line you should use the following command: 

/usr/ldap/bin/slapd 

8.1.7 Administration interface - Web 

From the Directory Server Web Admin you can perform several administrative 
task such as: 

• Configure a database 

• Configure a replica 

• Start up and shut down the server 

• Define an ACL 

• Add and delete suffixes 

• Add entries to the directory 

To use the Directory Web Admin you have to start up a Web browser and type 
in the Location field http://hostanme/idaFi 




0 Introduction 



Logon !o IBM SecureWay Director/ I 



Ready 

IBM SecnreWaj Dfrectoiy Saver Administration 



IBM* 



A logon is required to use this service. 

Please enter a distinguished LDAP user same and password and cfick 
Logon. 




Figure 405. Idap Web admin 
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For the user ID specify cn=root or the user that you specified in the 
administrator DN and password section in Figure 401 on page 413. 

For the password type the password that you specified in the administrator 
DN and password section and click the Logon button. 

8.1.8 DMT interface 

Use the DMT tool to: 

• Connect to one or more directory servers via SSL or non-SSL 
connections. 

• Display server properties and rebind to the server. 

• List, add, edit, and delete schema attributes and object classes. 

• List, add, edit, and delete directory entries. 

• Modify directory entry ACLs. 

• Search the directory tree. 

You can configure the tool to automatically connect to one or more servers 
and to log in particular Distinguished Names (DNs) when it is started. To 
configure the tool, edit the /usr/ldap/etc/dmt.conf DMT configuration file. For 
example, the property file contains these lines: 

• serverl .url=ldap://localhost:389 

• server! .security.bindDN= 

• server1.security.password= 

• server1.security.ssl.keyclass= 

8.1.8.1 Log on to a server 

If a directory user DN and password are not provided in the DMT 
configuration file, the tool connects as an anonymous user when it is started. 
Although an anonymous user can browse the directory tree and schema, to 
perform directory updates, in most instances, you need to log on as a 
directory user. To modify the directory server schema you must log on as the 
server administrator. To log on as a different user: 

1. Click Server -> Rebind. 

2. Provide the user DN and password. 

3. Press Enter. 

To start the DMT tool enter dmt &. 
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Figure 406. DMT 



For more information about how to use this tool, see: 

http: //www-4 . ibra. corri/software/netvorkydirectory/ 



8.1.9 Configuration files - attributes and objects classes 

The file /etc/slapd.conf contains configuration properties such as the SSL 
port, DB2 user, admin DN, and the admin password. 



>14II90IR3W)tR3c/ra^ 
M^j2>cEttb/jFa2V0b7B£2]cTv\^^ 
adraiifW •aosroot" 

# IBM SecureWay Directory Server Configuration Pile V3.1.1 for ATX 

# CWJTICN: EDIT THIS PILE WITH CRSE 

# We recoratEai naJcing all r^r^>a through the server administratim interface. 
sysLogLevelm 
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erxorlog/tmp/slapd . errors 
includeSchema /etc/ldapschona/V3 .system, at 
includeSdbema /etc/ldapschenB/V3 . Ibm.at 
includeScherna /etc/ldapechema/V3 .user . at 
includeSchema /etc/ldapschema/V3 . system, oc 
includeSchema /etc/ldapscherra/V3 .UatLoc 
iiicludeSchema /etc/ldapscheraa/V3 .user.oc 
includeSctea /etx:/ldapschgma/V3 .ldapsyntaxes 
includeScheraa /etc/ldapGchema/V3 .naffrhingrules 

# The next file is for schema changes. It's empty when the package is installed 
includeSchema /etc/ldapschema/V3 .modifiedschema 

scfaemacbeck. V3_lenient 
port389 
securePort636 
seouritynone 

#sslAuth options: serverauth/serverr!l i pntvmth 

sslAuth serverautb, 

sslOertificate none 

sslCipberSpecs 12288 

ssllteyRingpile key.kdb 

sslKey&ix^ileBtaone 

TnaxthteadB250 

waitingthreads 75 
tffZTTP, rp it <3 T , i1 * a On r mpr* ' i rm« on 
tinE3LimiC900 
si tjpI irattSOO 

#pwencryptian options: imask/nane/crypt/SHA 
pwencryptioa irnask 

HflBHHHfMlflfffftf H f l finff Ifflff »fl»irflHHfnifl H Hff » flfMI ffffff HTf fl rf f Mf fMMUl fl f f fl ff » » » ff fl H flfl » flff ff HH f>fffJ 

# ldcf datahase definitions 

mmmmmmmmmmmmmmmmmmmmmmmmmmmmm 

database ldcf 
suffix "cn=8Chema" 

nnnnnfTfTrrnnw rinnnfffrnnrrnnfTrrnnrrrrnfrfrnrTr fT i rrr irrrrrrrr r*7 r rrr"" """ """"""""" 

# rdbra database definitions 

^ HMff fnnMMf f J n fn; u fi >Mf f^n fu; Nff f r f n; f7 u m rarr; fnr fur rr rr nr> fn;fr gffff n rMMf ur; fMMKf rj fffMMfn f/rnifff^j 

databaserdbni 

plugin ^^taflP /lib/libbac3c-rdbm.a rdbmjDactend_init 

suffix o=rEM,c=CE w 

dbInstanaeldapcSb2 
dbuserpw 

>14SNxxL9SSF^/qrS\^imj^ 



dbuseridldapa02 

suffix "cnslocalhost" 
readCol}Off 

# point path at your changelog conf file and uncament 

# (it must be full path) 

^include /et^/ldapscnerta/slapd.cl . conf 



If you want to add a new object, modify or delete classes or attributes you can 
use the DMT tool. This tool also lets you know how the standard object 
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classes are created. Any attribute or class modification dynamically changes 
the directory schema. 

To add an object click Schema -> Object Classes -> Add Object class. 

To add an attribute click Schema -> Attributes -> Add attribute. 
For further information see the SecureWay Directory Web site at: 

http: //www-4 . dJbra. com/sof tware/netwrk/directory/ . 

8.1.10 LDAP commands 

We now show you how to use some of the more important LDAP commands 
from the user's point of view. There are more specific IBM SecureWay LDAP 
commands for administrative purposes. Other vendors who have 
implemented these commands may be using different flags. 

8.1.10.1 LDIF format 

LDAP Data Interchange Format (LDIF) is a format for representing LDAP 
entries in text form. It is widely used and accepted as a de-facto standard. 
LDIF is used by the Idapmodify, Idapadd, and Idapsearch command-line 
utilities. The basic form for an entry in an LDIF file is as follows: 

• dn: distinguished name> 

• objectClass: <object class> 

• objectClass: <object dass> 

• <attrtype>: <attrvalue 

• <attrtype>: <attrvalue> 

An LDIF file consists of a series of records separated by a blank line. A record 
is a directory entry with a mandatory DN and at least an objectClass if the 
record is a new entry. If the record is for an update only, the DN is required. 
Some attributes, required by an objectClass, must be defined. Attribute 
values can be clear text, such as a name, or they can be Base64 encoded 
binary data, such as for a JPEG picture. 

8.1.10.2 The Idapmodify and Idapadd utilities 

The Idapmodify utility is a command-line utility built around the ldap_modify() 
API. The utility opens a connection to an LDAP server, binds to the server, 
and modifies an entry. The entry information is read from standard input or 
from a file. The Idapadd utility is implemented as a renamed version of 
Idapmodify. The Idapadd works the same way as the Idapmodify with the -a 
flag set. The syntax of the utility is: 
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ldapmodify [options] [-f <ldif input file>] 
Idapadd [options] [-f <ldif input file>] 

Some options are: 

• -h host LDAP server host name 

• -p port LDAP server port number, default 389 

• -D dnbind dn by default anonymous 

• -w bind password 

• -R specifies that referrals are not to be automatically followed 

• -M manage referral objects as normal entries 

• -V LDAP protocol version (2 or 3; default is 3) 

• -C charset character set name to use, as registered with 

IANA 

• -b Assumes that any values that start with a / are binary values, and that 

the actual value is in a file whose path is specified in the 
place where values normally appear 

• -c continuous operation; do not stop processing on error 

• -n show what would be done but don't actually do it 

• -v verbose mode 

• -d level set debug level in LDAP library 

Examples 

Following are some examples using the LDAP commands: 

Idapadd -h rs600030 -D *cn=root" -w swall7r -f add.ldif 

This is the add.ldif's contents: 



oop^farisa , c?u=l'iau , o=ibm, c=us 

dbjectclass=*Persaa 

abj ectdasB-inetOrgPersaa 
cbjectclass^top 

uicfcMarisa 

trail=*feDrisa®ar.ibiTi.caTi 
ca^Marisa 

userPassward=swall7r 



Chapter 8. Directory Services 



421 



Now let's modify the Marisa's mail attribute: 

Idapraodify -h rs600030 -D "cn=root" -w ewall7r -d mod.ldif 



oo=Warisa f ou^nSO,cteibrti / c=us 

dDjectclas6=ePersan 

obj ect class ^person 

db j ect class =inetQrgPerscti 

dbjectclass=top 

nail=ci rRManfiftr . itan. com 



To validate the change we ran the Idapsearch command: 

ldapsearch -h rs600030 -b "ou=IT90,o=IBM,c=US" cn=MariBa 



C3i?=*ferisa,ou?=IT30,CfeilTi,c=us 

so=cic£tfan 

uid=Marisa 

oorfterisa 

ctyj Gctclass=€PexBon 
cbj ectclasB*=person 
0bjectcIa6S=ijQfitOrgPerBcci 
dbjectclass=tcp 



8.1.10.3 The Idapsearch utility 

The idapsearch utility is a command-line utility built around the 
ldap_search() API. The utility opens a connection to an LDAP server, binds to 
the server, and performs a search using a specified search filter. If the 
request finds one or more entries, the requested attributes are retrieved, and 
the entries and values are printed to standard output. If no attributes are 
specified, all attributes associated with each returned entry are displayed. 
The syntax is: 

Idapsearch [options] filter [attributes] 

The significant parameter options for the Idapsearch tool are: 

• -h LDAP server host name 

• -p LDAP server port number 

• -D bind dn 

• -w bind password 

• -b base dn for search; LDAP_BASEDN in environment is default 

• -s search scope (base, one, or sub) 
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• -a how to reference aliases (never, always, search, or find) 

• -I time limit (in seconds) for search 

• -z size limit (in entries) for search 

• -f perform sequence of searches using filters in file 

• -A retrieve attribute names only (no values) 

• -R do not automatically chase referrals 

• -M manage referral objects as normal entries 

• -V LDAP protocol version (2 or 3; default is 3) 

• -C character set name to use, as registered with IANA 

• -B do not suppress printing of non-ASCII values 

• -L print entries in LDIF format (-B is implied) 

• -F print separation between attribute names and values 

• -t write values to files in /tmp 

• -n show what would be done but don't actually do it 

• -v run in verbose mode 

• -d set debug level to level in LDAP library 

The search filter, in many cases, will either be a simple attribute search (such 
as cn=Smith) or for all attributes (cn=*). Search filters, however, can be fairly 
complex, and there is a separate RFC (RFC 2254) that you should refer to if 
you need all the details. The following is a brief description of search filters. A 
search filter defines criteria that an entry must match to be returned from a 
search. The basic component of a search filter is an attribute value assertion 
of the form: 

attribute operator value 

For example, to search for a person named John Smith, the search filter 
would be cn=John Smith. In this case, cn is the attribute, = is the operator, 
and John Smith is the value. This search filter matches entries with the 
common name John Smith. Table 9 on page 424lists the operators for search 
filters. 
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Table 9. Operators 



Operator 


Description 


Example 




Returns entries whose attribute is 
equal to the value. 


cn=John Smith finds the 
entry with the common 
name John Smith. 


>= 


Returns entries whose attribute is 
greater than or equal to the value. 


sn>=smith finds all entries 
from smith to z\ 


<- 


Returns entries whose attribute is 
less than or equal to the value. 


sn<=smith finds all entries 
from a* to smith. 




Returns entries that have a value 
set for that attribute. 


sn=* finds all entries that 
have the sn attribute. 




Returns entries whose attribute 
value approximately matches the 
specified value. Typically, this is 
an algorithm that matches words 
that sound alike. 


sn~= smit might find the 
entry "sn=smith". 



The character matches any substring and can be used with the = operator. 
For example, cn=J*Smi* would match John Smith and Jan Smitty. Search 
filters can be combined with Boolean operators to form more complex search 
filters. The syntax for combining search filters is: 

( or T (filterl) (filter2) (filter3) ...) 

(T (filter)) 

The Boolean operators are listed in the following table: 



Table 10. Operators 



Boolean operator 


Description 


& 


Returns entries matching all specified fitter 
criteria. 


I 


Returns entries matching one or more of 
the filter criteria. 


! 


Returns entries for which the filter is not 
true. This operator can only be applied to 
a single filter. ( 1 (filter) ) is valid, 
but (t (filterl) (filter2) ) is 
not. 
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Examples: 

1. Retrieve all the entries with a person object defined; 

Idapsearch -h rs600030 -b "o=IBM,c=US n obj ectclass=person 

2. Retrieve all the entries with an e-mail ending in "ibrnxom"; 

Idapsearch -h rs600030 -b "o=IBM,c=U5 n mail=*iixn. com 

3. Retrieve all the entries with cn=Marina and mail=*ibm.com; 

Idapsearch -h rs6 00030 -b "o=IBM,c=U5 n 
■ (& (cn=Marisa) (mail=*ibm. com) ) " 

Note that we used " * in the filter. The reason was that on AIX the ksh 
preprocesses the () directive with a " and doesn't preprocess the 
contents. 

4. Retrieve all entries with mail=*ibm.com and cn not equal to Karina, root; 

Idapsearch -h rs600030 -b n o=IBM,c=US" 

" (&(mail=*ibm.com) (I ( | (cn=Karina) (cn=root) ) ) ) " 

8.1.10.4 The Idapdelete utility 

The Idapdelete utility is built around the ldap_delete() API. The utility opens a 
connection to an LDAP server, binds to the server, and deletes one or more 
entries. The distinguished names (DNs) of the entries to delete are read from 
standard input or from a file. 

The syntax is: 

Idapdelete [options] [DNs] 
Idapdelete [options] [-f file] 

where: 

dn: one or more items to delete 

fUe: name of input file containing items to delete 

If neither dn or file is specified then items are read from standard input. The 
options are: 

-h LDAP server host name 
-p LDAP server port number 
-D bind dn 
-w bind password 

-Z use a secure Idap connection (SSL) 
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-K file to use for keys 

-P keyfile password 

-N private key name to use in keyfile 

-m perform SASL bind with the given mechanism 

-R do not chase referrals 

-M Manage referral objects as normal entries 

-O maximum number of referrals to follow in a sequence 

-V LDAP protocol version (2 or 3; default is 3) 

-C character set name to use, as registered with IANA 

-c continuous operation; do not stop processing on error 

-n show what would be done but don't actually do it 

-v verbose mode 

-d level (set debug level in LDAP library 
Examples: 

1 . Delete the entries with cn=Karina: 

ldapdelete -h rs6 00030 -D 1 "cn=root' r -w swall7r *cn=Karina, 

ou^rrso, o=ibm, c=us ff 

2. Delete two entries from a file called IdapDelete: 

/ N 

"cn^Marisa, ou^nso, o=IBM, c=GS n 
^ B cngQdg^iaT^,ousJT^O / (>=IBM,c=JE' , ^ 

ldapdelete -h rs600030 -D swall7r -f IdapDelete 

8.1.11 Configuring the Netscape address book to use LDAP 

The Netscape address book is an LDAP-enabled application, which means 
that it can get information from an LDAP directory. Other products like 
Microsoft Internet Explorer are LDAP enabled too. 

In these examples we show you how to set up the Netscape address book to 
use IBM SecureWay Directory V3.1.1. 

1. Start the Netscape address book. 
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ipf Address Book IIeHO 




jg Netcenter M... 
p| InfoSpace DL.. 
§ Verin^ Die... 



IS 




Figure 407. Netscape address book 



2. Create a new directory. 

Click File -> New Directory and you should see the dialog box shown in 
Figure 408. 




Figure 408. Directory Server Property dialog box 



The fields are: 
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• Description: Title description is optional 

• LDAP Server: Host name of the Directory Server 

• Search Root: Base DN 

• Port Number: By default 389 

• Don't show more than: Maximum number of entries returned 

• Secure: Use SSL 

• Login with name and password: Used to bind with user ID and password 
3. To see all entries, type * in the Show names containing field: 





Test Secure.. 



Netcenter M... 
InfoSpace DL. 
Verisign Ore... 



21 Km 
§3 Maris* 
m WAS 



karina@ar.fcm.com hm 
. MaRsa@ar.fcm.com jbm 
bm 




Figure 409. Search 



8.1.12 WebSphere and LDAP 

WebSphere supports authentication mechanisms based on validating 
credentials such as user ID and password, certificates, or tokens. Credentials 
are verified against a user registry supporting such a schema. For example, 
user IDs and password-based authentication can be based on the LDAP user 
registry where authentication is performed using an LDAP bind. A certificate 
validation list may be used in cases where authentication of the user is based 
on the client certificate presented by the user over a mutual SSL connection. 
WebSphere supports a three-party authentication schema, one in which the 
client principal and server principal are authenticated to a mutually trusted 
third-party. The third-party in this case is the authentication token server. An 
advantage of a three-party schema is that administration of the user registry 
can be controlled centrally. 
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WebSphere supports the following list of LDAP Directory Servers: 

• Netscape Directory Server Version 3.x and 4.x 

• Secure Way Directory Server Version 2.1 and 3.1.1 

• Lotus Domino Version 4.6 and 5.0 

Additional attributes are available for customizing any of the default filters to 
fit a Directory Server not listed above. 

8.1.13 Configuring WebSphere to use LDAP 

Start the WebSphere Advanced Administrative Console. 

1. Select the Tasks tab, double-click the Security option and you will see a 
window similar to Figure 410: 




Figure 410. Security global settings 



2. Select Specify Global Settings and click the Enable Security field. 

Enable Security: Specifies whether to enable or turn off server security. 
If you deselect this field all the security options specified on resources 
will be unprotected. 
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Security Cache TimeOut: Specifies how many seconds the server 
should cache security information received from the user registry 
(Operating System registry or Directory Server "LDAP"). 

3. Select the Application Defaults tab to specify the following properties: 
Realm Name: Is the security domain where the user will be 
authenticated? If the principal tries to access a resource in a different 
realm, the principal will be prompted to log in to the new realm. It is 
used if Single Sign On (SSO) is used. 

Challenge Type: This option specifies the mechanism used by the 
principal to interchange credentials. If you select Basic, it means that 
the Web browser will prompt the principal for a user ID and password. 




Figure 411. Global settings • Applications Defaults 



4. Click the Authentication Mechanism tab. On this page you specify the 
mechanism used by the security server to authenticate the principal's 
credentials. See Figure 412 on page 431 . 
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Lightweight Third Party Authentication (LTPA): Select this option to use 
the LDAP directory server as the registry system. 

Token Expiration: Specifies how many minutes can pass before a client 
using an LTPA token must be authenticated again. We used the default 
value. 




5. Click the User Registry tab. On this page we specify basic information to 
use the LDAP Directory Server as shown in Figure 413 on page 433. 
These are the attributes that you should change: 

Security Server ID: Type a valid user ID registered in the LDAP 
Directory server used by the Application Server V3 Security server. 
The user ID should have some administrative privileges. 

Security Server Password: Type the password for the security server ID 
user. 
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Directory Type: Select the directory to be used. In our case we used 
SecureWay. 

Host: Type the host name where the LDAP directory is running. In this 
example it is rs600030. 

Port: Specify the LDAP directory port, which by default is 389. We used 
the default value. 

Base Distinguished Name: Use this property to specify the starting 
point for LDAP searches. If you plan to use Domino directory you can 
leave this field blank. In this example we used ou=ITSO,o=IBM,c=US. 

Bind Distinguished Name: Use this property to specify the DN to be 
used for the application server. If you leave it blank the Application 
Server binds using the anonymous ID. In this field we used the LDAP 
administrator cn=root. 

Bind Password: Use this field to specify the password used to bind to 
the LDAP directory. We used the LDAP administrator's password. 

Note: If you get the exception 

org.omg.CORBA.TRANSACTION_ROLLEDBACK when you click the 
Finished button, it means that you probably specified an incorrect user 
ID or password. 
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Figure 413. User Registry properties 



6. Click the Finished button. 

Note: For any change made on the global security settings you must 
restart the node. To do so, click Topology -> WebSphere Admin Domain 
-> Host Name (rs600030). Then right-click the mouse button and select 
stop or restart. You must leave the administrative console. 

You can customize more LDAP attributes such as search filters and certificate 
mapping as shown in Figure 414: 
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Figure 414. Advanced properties 



7. The next step consists of applied security on an application. This means 
performing the following steps: 

a. Configure an enterprise application. 

b. Configure application security. 

c. Configure resource security. 

d. Assign permissions. 

For more information about how to perform these tasks see the 
WebSphere documentation available in the directory 
/usr/WebSphere/AppServer/web/doc/begin_here/index.html 

8.1.14 JNDI 

JNDI defined by Sun Microsystems provides naming and directory functions 
to Java programs. JNDI is an API independent of any specific directory 
service implementation. 

The definition prevents, by design, the appearance of any 
implementation-specific artifacts in the API. The API is designed to cover the 
common case. JNDI was developed as part of Java Enterprise API set which 
also includes Enterprise Java beans (EJB) and Java Database Connectivity 
(JDBC). The EJB specification has a special relationship with JNDI because 
EJB uses this mechanism to find Entity beans or Sessions beans. 
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